From 1b50e6b0af2dc7f9d785e886a79784e3c6accc8b Mon Sep 17 00:00:00 2001 From: Rutger Broekhoff Date: Mon, 29 Apr 2024 00:13:51 +0200 Subject: Write man pages for Gitolfs3 --- docs/man/gitolfs3-authenticate.1 | 33 +++++++++++ docs/man/gitolfs3-server.1 | 124 +++++++++++++++++++++++++++++++++++++++ docs/man/gitolfs3-shell.1 | 36 ++++++++++++ 3 files changed, 193 insertions(+) create mode 100644 docs/man/gitolfs3-authenticate.1 create mode 100644 docs/man/gitolfs3-server.1 create mode 100644 docs/man/gitolfs3-shell.1 (limited to 'docs/man') 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). -- cgit v1.2.3