aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorLibravatar Rutger Broekhoff2024-04-29 00:13:51 +0200
committerLibravatar Rutger Broekhoff2024-04-29 00:13:51 +0200
commit1b50e6b0af2dc7f9d785e886a79784e3c6accc8b (patch)
tree067bf7d84082660eee7af4e32703b66eb752cdc7 /docs
parent14cf035c4f3a749ff696e2cf5bf08d11279a6918 (diff)
downloadgitolfs3-1b50e6b0af2dc7f9d785e886a79784e3c6accc8b.tar.gz
gitolfs3-1b50e6b0af2dc7f9d785e886a79784e3c6accc8b.zip
Write man pages for Gitolfs3
Diffstat (limited to 'docs')
-rw-r--r--docs/man/gitolfs3-authenticate.133
-rw-r--r--docs/man/gitolfs3-server.1124
-rw-r--r--docs/man/gitolfs3-shell.136
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 @@
1.TH GITOLFS3-AUTHENTICATE 1 2024-04-29 Gitolfs3 "Gitolfs3 Manual"
2.SH NAME
3git-lfs-authenticate \- Git LFS authentication agent for Gitolfs3
4.SH SYNOPSIS
5.B git-lfs-authenticate
6<repository>
7upload/download
8.SH DESCRIPTION
9.B git-lfs-authenticate
10is a Git LFS authentication agent for Gitolfs3.
11When accessible from the Git shell,
12.B git-lfs-authenticate
13can authorize users to access the Gitolfs3 Git LFS server.
14
15Although
16.B git-lfs-authenticate
17does assume that the user can be trusted, as they have access to the server,
18it is a good idea to restrict the shell for the \fIgit\fR user.
19For example, the user should not be able to modify environment variables, nor
20should the user be able to execute any arbitrary command.
21The Git shell provided by Gitolfs3 may be a good option. (See
22.BR gitolfs3-shell (1).)
23.SH ENVIRONMENT VARIABLES
24.TP
25.B GITOLFS3_HREF_BASE
26.B Required.
27The base URL at which the Gitolfs3 server is available.
28Must end with a slash.
29.TP
30.B GITOLFS3_KEY_PATH
31.B Required.
32The path to the key which is used to authorize the request to the Gitolfs3
33server.
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 @@
1.TH GITOLFS3-SERVER 1 2024-04-29 Gitolfs3 "Gitolfs3 Manual"
2.SH NAME
3server \- Gitolfs3 Git LFS server
4.SH SYNOPSIS
5.B server
6.SH DESCRIPTION
7.B server
8is the Gitolfs3 Git LFS server. It is primarily configured using environment
9variables.
10A complete reference of the environment variables can be seen below.
11
12.B Important note:
13The working directory of the Gitolfs3 server should be the folder containing all Git repositories.
14Otherwise, repositories will not be recognized (and nothing will work).
15
16The Gitolfs3 server uses S3-compatible services as backing storage.
17In the configured S3 bucket, a familiar structure is used:
18.in +2
19lfs-test.git/ ................. repository name
20.in +2
21lfs/objects/ ................ namespace
22.in +2
234e/ ....................... first byte of the object ID (OID)
24.in +2
257b/ ..................... second byte of the OID
26.in +2
274e7bfdb[...]11ce013 ... OID (SHA256)
28.in -10
29
30Public and private repositories are distinguished using the presence of a
31\fIgit-daemon-export-ok\fR file in the bare repository.
32Unauthenticated users accessing the service over the public internet are
33allowed to download all files from all public repositories.
34Unauthenticated users accessing the service over a trusted network are allowed
35to download all files from all repositories, so also from all private
36repositories.
37Only authenticated users are authorized to upload files.
38For information on access control in private networks, please see the
39documentation for the environment variable
40.BR GITOLFS3_TRUSTED_FORWARDED_HOSTS .
41
42This server can be used in combination with the Gitolfs3 Git LFS authentication
43agent (see
44.BR gitolfs3-authenticate ).
45For more information, please see the documentation for the environment variable
46.BR GITOLFS3_KEY_PATH .
47.SH ENVIRONMENT VARIABLES
48.TP
49.B GITOLFS3_S3_SECRET_ACCESS_KEY_FILE
50.B Required.
51Path to the Secret Access Key to access the configured S3 service.
52.TP
53.B GITOLFS3_S3_ACCESS_KEY_ID_FILE
54.B Required.
55Path to the Access Key ID to access the configured S3 service.
56.TP
57.B GITOLFS3_S3_REGION
58.B Required.
59The S3 region which the configured bucket is in.
60.TP
61.B GITOLFS3_S3_ENDPOINT
62.B Required.
63The S3 endpoint to use.
64Whether using Amazon S3 or another provider, this URL always be provided.
65In the case of Scaleway Object Storage, this may look like
66\fIhttps://s3.nl-ams.scw.cloud\fR for the region \fInl-ams\fR.
67.TP
68.B GITOLFS3_S3_BUCKET
69.B Required.
70The S3 bucket to use.
71Should be in the configured region (see
72.BR GITOLFS_S3_ENDPOINT ).
73.TP
74.B GITOLFS3_BASE_URL
75.B Required.
76The base URL under which the Gitolfs3 server itself runs.
77This is required so that the server can generate hyperlinks that refer to
78itself.
79.TP
80.B GITOLFS3_KEY_PATH
81.B Required.
82Path to the key that is used to generate and verify tags (MACs) for requests.
83Must correspond with the key used by
84.BR gitolfs3-authenticate (1),
85if using.
86.TP
87.B GITOLFS3_LISTEN_HOST
88.B Required.
89The host on which the Gitolfs3 server should listen.
90.TP
91.B GITOLFS3_LISTEN_PORT
92.B Required.
93The port on which the Gitolfs3 server should listen.
94.TP
95.B GITOLFS3_DOWNLOAD_LIMIT
96.B Required.
97The maximum amount of file bytes which may be downloaded within the span of an
98hour.
99
100The server keeps track of the amount of bytes downloaded in the last hour in a
101file called \fI.gitofls3-dlimit\fR, which it stores in its working directory.
102Every hour, the counter is reset.
103When the server crashes, the counter is not reset.
104This means that the implementation is pretty messy, and that repeated crashes
105of the server turn this 'hour' into practical 'infinity'.
106
107The main purpose of this feature is to prevent incurring unforeseen egress
108costs.
109
110.B Note:
111Only untrusted hosts are held to this limit.
112.TP
113.B GITOLFS3_TRUSTED_FORWARDED_HOSTS
114.B Optional.
115A comma-separated list of hosts which can be classified as 'trusted'.
116
117If a request comes in for which the X-Forwarded-Host header contains one of the
118hosts in this list, then the user is automatically generated read access to all
119repositories, regardless of the presence of a \fIgit-daemon-export-ok\fR file.
120Furthermore, presigned URLs are returned for download requests, instead of
121downloads being proxied through the Gitolfs3 server.
122
123.B Note:
124There 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 @@
1.TH GITOLFS3-SHELL 1 2024-04-29 Gitolfs3 "Gitolfs3 Manual"
2.SH NAME
3shell \- Gitolfs3 shell
4.SH SYNOPSIS
5.B shell
6-c <command>
7.SH DESCRIPTION
8.B shell
9is the Gitolfs3 shell.
10.SH COMMANDS
11.TP
12.B git-receive-pack \fR<repsitory>\fB
13Alternatively, using \fBgit receive-pack\fR is also allowed.
14No other arguments nor options than indicated above are processed nor allowed.
15See
16.BR git-receive-pack (1).
17.TP
18.B git-upload-archive \fR<repsitory>\fB
19Alternatively, using \fBgit upload-archive\fR is also allowed.
20No other arguments nor options than indicated above are processed nor allowed.
21See
22.BR git-upload-archive (1).
23.TP
24.B git-upload-pack \fR<repsitory>\fB
25Alternatively, using \fBgit upload-pack\fR is also allowed.
26No other arguments nor options than indicated above are processed nor allowed.
27See
28.BR git-upload-pack (1).
29.TP
30.B git-lfs-authenticate \fR<repository> upload/download\fB
31Outputs a JSON document containing a reference to the Gitolfs3 Git LFS endpoint
32for the indicated repository and an accompanying tag/MAC to authenticate with
33the Gitolfs3 server.
34Only valid for the indicated repository and operation.
35See
36.BR gitolfs3-authenticate (1).