From 29c576de63a3de6da6a2f4909f151b3d5d157060 Mon Sep 17 00:00:00 2001 From: Rutger Broekhoff Date: Tue, 30 Apr 2024 02:20:00 +0200 Subject: Improve man pages Added an explanation on the type of key that is expected. Also tried to fix layout of the path structure explanation in gitolfs3-server(1), so that it also looks okay when rendered as a PDF. (On the PDF generated using mandoc it still looks a bit weird, but I don't think I'll try to solve that right now.) --- docs/man/gitolfs3-authenticate.1 | 10 ++++++++++ docs/man/gitolfs3-server.1 | 32 +++++++++++++++++++++----------- 2 files changed, 31 insertions(+), 11 deletions(-) (limited to 'docs/man') diff --git a/docs/man/gitolfs3-authenticate.1 b/docs/man/gitolfs3-authenticate.1 index 3a9951e..3f44312 100644 --- a/docs/man/gitolfs3-authenticate.1 +++ b/docs/man/gitolfs3-authenticate.1 @@ -31,3 +31,13 @@ Must end with a slash. .B Required. The path to the key which is used to authorize the request to the Gitolfs3 server. +The key must be 128-character hexadecimal string, i.e., a 64-byte number. +Such a key can, for example, be generated using OpenSSL, with the following +command: + + openssl rand -hex 64 + +Note that the Gitolfs3 server must be configured to use exactly the same key +for +.B gitolfs3-authenticate +to function. diff --git a/docs/man/gitolfs3-server.1 b/docs/man/gitolfs3-server.1 index f141bce..30f8cb5 100644 --- a/docs/man/gitolfs3-server.1 +++ b/docs/man/gitolfs3-server.1 @@ -15,18 +15,22 @@ 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 +.IP +.TS +tab(%); +l l +l l +l l +l l +l l. +lfs-test.git/ % repository name + lfs/objects/ % namespace + 4e/ % first byte of the object ID (OID) + 7b/ % second byte of the OID + 4e7bfdb[...]11ce013 % OID (SHA256) +.TE +.P 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 @@ -80,6 +84,12 @@ itself. .B GITOLFS3_KEY_PATH .B Required. Path to the key that is used to generate and verify tags (MACs) for requests. +The key must be 128-character hexadecimal string, i.e., a 64-byte number. +Such a key can, for example, be generated using OpenSSL, with the following +command: + + openssl rand -hex 64 + Must correspond with the key used by .BR gitolfs3-authenticate (1), if using. -- cgit v1.2.3