diff options
| -rw-r--r-- | Makefile | 5 | ||||
| -rw-r--r-- | skein-infra.8 | 56 | ||||
| -rw-r--r-- | skein.7 | 132 |
3 files changed, 192 insertions, 1 deletions
@@ -1,6 +1,7 @@ PREFIX ?= /usr/local LIBEXECDIR ?= ${PREFIX}/libexec SBINDIR ?= ${PREFIX}/sbin +MANDIR ?= ${PREFIX}/share/man CFLAGS ?= -O2 -pipe -s CFLAGS += -Wall -Wextra -Wpedantic -Werror @@ -10,9 +11,11 @@ LDFLAGS ?= -static cgit-about-filter: cgit-about-filter.c ${CC} -o $@ ${CFLAGS} ${LDFLAGS} $< -install: cgit-about-filter skein-infra +install: cgit-about-filter skein-infra skein.7 skein-infra.8 install -D -m 755 -t '${DESTDIR}${LIBEXECDIR}/skein' cgit-about-filter install -D -m 755 -t '${DESTDIR}${SBINDIR}' skein-infra + install -D -m 644 -t '${DESTDIR}${MANDIR}/man7' skein.7 + install -D -m 644 -t '${DESTDIR}${MANDIR}/man8' skein-infra.8 clean: rm cgit-about-filter diff --git a/skein-infra.8 b/skein-infra.8 new file mode 100644 index 0000000..5c7c400 --- /dev/null +++ b/skein-infra.8 @@ -0,0 +1,56 @@ +.Dd May 28, 2020 +.Dt SKEIN-INFRA 8 +.Os +.Sh NAME +.Nm skein-infra +.Nd set up devices and bind mounts for +.Xr skein 7 +.Sh SYNOPSIS +.Nm +.Ar setup +.Nm +.Ar teardown +.Sh DESCRIPTION +.Nm +is a utility which sets up all necessary devices and bind mounts for the +.Xr skein 7 +cgit infrastructure. +.Pp +The commands are as follows: +.Bl -tag -width Ds +.It Sy setup +Creates +.Pa /dev/null +under +.Ev SKEIN_CGIT_ROOT +and sets up all necessary bind mounts. +.Pp +Each user's git directory under +.Ev SKEIN_GIT_ROOT +is mounted on the corresponding +.Pa repos.avail/ +mount point in their cgit home directory. +.It Sy teardown +Deletes +.Pa /dev/null +and all existing bind mounts under +.Ev SKEIN_CGIT_ROOT . +.El +.Sh ENVIRONMENT +.Bl -tag -width Ds +.It Ev SKEIN_CGIT_ROOT +The +.Xr skein 7 +cgit infrastructure. +Defaults to +.Pa /srv/cgit . +.It Ev SKEIN_GIT_ROOT +The +.Xr skein 7 +repository infrastructure. +Defaults to +.Pa /srv/git . +.El +.Sh SEE ALSO +.Xr skein 7 , +.Xr mount 8 @@ -0,0 +1,132 @@ +.Dd May 28, 2020 +.Dt SKEIN 7 +.Os +.Sh NAME +.Nm skein +.Nd secure cgit hosting with +.Xr slowcgi 8 +.Sh DESCRIPTION +.Nm +is a framework for building a secure cgit hosting platform. +It uses +.Xr slowcgi 8 +to provide cgit to modern web servers that only support FastCGI and +keeps the entire cgit platform jailed in a chroot. +Users may host multiple cgit instances, each with their own repositories +and cgit configuration. +.Pp +The framework is comprised of two main parts, the cgit infrastructure +and the repository infrastructure. +These two parts exist independent of each other, allowing other +applications access to repositories without having to be integrated into +the framework. +.Pp +.Nm +utilizes bind mounts to allow access to the repositories from within the +chroot. +Each user will have their available repositories accessible through a +mount point in their cgit home directory. +Bind mounts and other necessary devices may be set up using +.Xr skein-infra 8 . +.Sh REPOSITORY INFRASTRUCTURE +Bare Git repositories are stored in per-user folders under +.Pa /srv/git . +.Pp +Repositories that are meant to be accessed by cgit should be readable by +the user running +.Xr slowcgi 8 . +.Sh CGIT INFRASTRUCTURE +The cgit infrastructure exists in +.Pa /srv/cgit . +This directory also acts as the chroot directory for +.Xr slowcgi 8 , +containing the cgit CGI executable itself, along with other programs +relevant to cgit instances, such as formatters and filters like +.Xr mandoc 1 +or +.Xr lowdown 1 , +and archivers or compression programs like +.Xr tar 1 +or +.Xr gzip 1 . +.Pp +Each user owns a home directory which contains a mount point +.Pa repos.avail/ +for the user's available repositories and +a folder +.Pa instances/ +that contains every instance managed by that user. +.Pp +For example, a setup with two users may look like this: +.Bd -literal -offset indent +/srv/cgit +├── bin +│ ├── cgit +│ └── mandoc +└── home + ├── ada + │ ├── instances + │ │ └── cgit.ada.example.org/ + │ └── repos.avail/ + └── joe + ├── instances + │ ├── cgit.joe.example.org/ + │ └── private-cgit.joe.example.org/ + └── repos.avail/ +.Ed +.Pp +A single cgit instance is comprised of the following files and +directories: +.Bl -tag -width Ds +.It Sy config +The runtime configuration for cgit, as per +.Xr cgitrc 5 . +.It Sy repos/ +A directory holding a list of repositories available to that cgit +instance, in the form of symbolic links pointing to repositories in +.Pa repos.avail/ . +.It Sy site/ +A directory containing static resources needed for cgit. +This is also the website's root directory. +.El +.Pp +For example, a single instance may look like this: +.Bd -literal -offset indent +cgit.joe.example.org +├── config +├── repos +│ ├── dotfiles.git@ -> ../../../repos.avail/dotfiles.git +│ └── project.git@ -> ../../../repos.avail/project.git +└── site + ├── cgit.css + ├── favicon.ico + └── logo.png +.Ed +.Sh WEB SERVER CONFIGURATION +Web servers connect to +.Xr slowcgi 8 +via its unix socket. +For simple setups it is sufficient for the web server to set +.Ev SCRIPT_FILENAME +and +.Ev CGIT_CONFIG . +Note that static files such as +.Pa cgit.css +or +.Pa cgit.png +need to be excluded from FastCGI processing. +.Pp +For example, a FastCGI directive may look like this: +.Bd -literal -offset indent +fastcgi / /run/slowcgi.cgit.sock { + env SCRIPT_FILENAME /bin/cgit.cgi + env CGIT_CONFIG /home/joe/instances/cgit.joe.example.org/config + + except /cgit.css /cgit.png /favicon.ico /robots.txt +} +.Ed +.Sh SEE ALSO +.Xr cgitrc 5 , +.Xr mount 8 , +.Xr skein-infra 8 , +.Xr slowcgi 8 |