Write man pages for Gitolfs3

3 files changed, 193 insertions, 0 deletions

diff --git a/docs/man/gitolfs3-authenticate.1 b/docs/man/gitolfs3-authenticate.1
new file mode 100644
index 0000000..67151e1
--- /dev/null
+++ b/docs/man/gitolfs3-authenticate.1
@@ -0,0 +1,33 @@
+.TH GITOLFS3-AUTHENTICATE 1 2024-04-29 Gitolfs3 "Gitolfs3 Manual"
+.SH NAME
+git-lfs-authenticate \- Git LFS authentication agent for Gitolfs3
+.SH SYNOPSIS
+.B git-lfs-authenticate
+<repository>
+upload/download
+.SH DESCRIPTION
+.B git-lfs-authenticate
+is a Git LFS authentication agent for Gitolfs3.
+When accessible from the Git shell,
+.B git-lfs-authenticate
+can authorize users to access the Gitolfs3 Git LFS server.
+
+Although
+.B git-lfs-authenticate
+does assume that the user can be trusted, as they have access to the server,
+it is a good idea to restrict the shell for the \fIgit\fR user.
+For example, the user should not be able to modify environment variables, nor
+should the user be able to execute any arbitrary command.
+The Git shell provided by Gitolfs3 may be a good option. (See
+.BR gitolfs3-shell (1).)
+.SH ENVIRONMENT VARIABLES
+.TP
+.B GITOLFS3_HREF_BASE
+.B Required.
+The base URL at which the Gitolfs3 server is available.
+Must end with a slash.
+.TP
+.B GITOLFS3_KEY_PATH
+.B Required.
+The path to the key which is used to authorize the request to the Gitolfs3
+server.
diff --git a/docs/man/gitolfs3-server.1 b/docs/man/gitolfs3-server.1
new file mode 100644
index 0000000..4f384cf
--- /dev/null
+++ b/docs/man/gitolfs3-server.1
@@ -0,0 +1,124 @@
+.TH GITOLFS3-SERVER 1 2024-04-29 Gitolfs3 "Gitolfs3 Manual"
+.SH NAME
+server \- Gitolfs3 Git LFS server
+.SH SYNOPSIS
+.B server
+.SH DESCRIPTION
+.B server
+is the Gitolfs3 Git LFS server. It is primarily configured using environment
+variables.
+A complete reference of the environment variables can be seen below.
+
+.B Important note:
+The working directory of the Gitolfs3 server should be the folder containing all Git repositories.
+Otherwise, repositories will not be recognized (and nothing will work).
+
+The Gitolfs3 server uses S3-compatible services as backing storage.
+In the configured S3 bucket, a familiar structure is used:
+.in +2
+lfs-test.git/ ................. repository name
+.in +2
+lfs/objects/ ................ namespace
+.in +2
+4e/ ....................... first byte of the object ID (OID)
+.in +2
+7b/ ..................... second byte of the OID
+.in +2
+4e7bfdb[...]11ce013 ... OID (SHA256)
+.in -10
+
+Public and private repositories are distinguished using the presence of a
+\fIgit-daemon-export-ok\fR file in the bare repository.
+Unauthenticated users accessing the service over the public internet are
+allowed to download all files from all public repositories.
+Unauthenticated users accessing the service over a trusted network are allowed
+to download all files from all repositories, so also from all private
+repositories.
+Only authenticated users are authorized to upload files.
+For information on access control in private networks, please see the
+documentation for the environment variable
+.BR GITOLFS3_TRUSTED_FORWARDED_HOSTS .
+
+This server can be used in combination with the Gitolfs3 Git LFS authentication
+agent (see
+.BR gitolfs3-authenticate ).
+For more information, please see the documentation for the environment variable
+.BR GITOLFS3_KEY_PATH .
+.SH ENVIRONMENT VARIABLES
+.TP
+.B GITOLFS3_S3_SECRET_ACCESS_KEY_FILE
+.B Required.
+Path to the Secret Access Key to access the configured S3 service.
+.TP
+.B GITOLFS3_S3_ACCESS_KEY_ID_FILE
+.B Required.
+Path to the Access Key ID to access the configured S3 service.
+.TP
+.B GITOLFS3_S3_REGION
+.B Required.
+The S3 region which the configured bucket is in.
+.TP
+.B GITOLFS3_S3_ENDPOINT
+.B Required.
+The S3 endpoint to use.
+Whether using Amazon S3 or another provider, this URL always be provided.
+In the case of Scaleway Object Storage, this may look like
+\fIhttps://s3.nl-ams.scw.cloud\fR for the region \fInl-ams\fR.
+.TP
+.B GITOLFS3_S3_BUCKET
+.B Required.
+The S3 bucket to use.
+Should be in the configured region (see
+.BR GITOLFS_S3_ENDPOINT ).
+.TP
+.B GITOLFS3_BASE_URL
+.B Required.
+The base URL under which the Gitolfs3 server itself runs.
+This is required so that the server can generate hyperlinks that refer to
+itself.
+.TP
+.B GITOLFS3_KEY_PATH
+.B Required.
+Path to the key that is used to generate and verify tags (MACs) for requests.
+Must correspond with the key used by
+.BR gitolfs3-authenticate (1),
+if using.
+.TP
+.B GITOLFS3_LISTEN_HOST
+.B Required.
+The host on which the Gitolfs3 server should listen.
+.TP
+.B GITOLFS3_LISTEN_PORT
+.B Required.
+The port on which the Gitolfs3 server should listen.
+.TP
+.B GITOLFS3_DOWNLOAD_LIMIT
+.B Required.
+The maximum amount of file bytes which may be downloaded within the span of an
+hour.
+
+The server keeps track of the amount of bytes downloaded in the last hour in a
+file called \fI.gitofls3-dlimit\fR, which it stores in its working directory.
+Every hour, the counter is reset.
+When the server crashes, the counter is not reset.
+This means that the implementation is pretty messy, and that repeated crashes
+of the server turn this 'hour' into practical 'infinity'.
+
+The main purpose of this feature is to prevent incurring unforeseen egress
+costs.
+
+.B Note:
+Only untrusted hosts are held to this limit.
+.TP
+.B GITOLFS3_TRUSTED_FORWARDED_HOSTS
+.B Optional.
+A comma-separated list of hosts which can be classified as 'trusted'.
+
+If a request comes in for which the X-Forwarded-Host header contains one of the
+hosts in this list, then the user is automatically generated read access to all
+repositories, regardless of the presence of a \fIgit-daemon-export-ok\fR file.
+Furthermore, presigned URLs are returned for download requests, instead of
+downloads being proxied through the Gitolfs3 server.
+
+.B Note:
+There must be no space between the comma-separated items.
diff --git a/docs/man/gitolfs3-shell.1 b/docs/man/gitolfs3-shell.1
new file mode 100644
index 0000000..56eac31
--- /dev/null
+++ b/docs/man/gitolfs3-shell.1
@@ -0,0 +1,36 @@
+.TH GITOLFS3-SHELL 1 2024-04-29 Gitolfs3 "Gitolfs3 Manual"
+.SH NAME
+shell \- Gitolfs3 shell
+.SH SYNOPSIS
+.B shell
+-c <command>
+.SH DESCRIPTION
+.B shell
+is the Gitolfs3 shell.
+.SH COMMANDS
+.TP
+.B git-receive-pack \fR<repsitory>\fB
+Alternatively, using \fBgit receive-pack\fR is also allowed.
+No other arguments nor options than indicated above are processed nor allowed.
+See
+.BR git-receive-pack (1).
+.TP
+.B git-upload-archive \fR<repsitory>\fB
+Alternatively, using \fBgit upload-archive\fR is also allowed.
+No other arguments nor options than indicated above are processed nor allowed.
+See
+.BR git-upload-archive (1).
+.TP
+.B git-upload-pack \fR<repsitory>\fB
+Alternatively, using \fBgit upload-pack\fR is also allowed.
+No other arguments nor options than indicated above are processed nor allowed.
+See
+.BR git-upload-pack (1).
+.TP
+.B git-lfs-authenticate \fR<repository> upload/download\fB
+Outputs a JSON document containing a reference to the Gitolfs3 Git LFS endpoint
+for the indicated repository and an accompanying tag/MAC to authenticate with
+the Gitolfs3 server.
+Only valid for the indicated repository and operation.
+See
+.BR gitolfs3-authenticate (1).