From 9050777231e3e4e1d43070d0e189a7ece7399eae Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Mon, 16 Jan 2017 02:47:27 +0000 Subject: [PATCH] WIP --- dgit-downstream-dsc.5.pod | 146 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 dgit-downstream-dsc.5.pod diff --git a/dgit-downstream-dsc.5.pod b/dgit-downstream-dsc.5.pod new file mode 100644 index 00000000..d8afcd4b --- /dev/null +++ b/dgit-downstream-dsc.5.pod @@ -0,0 +1,146 @@ +This guide is to help you if: + + * you are a distro which is a downstream of Debian (directly + or indirectly) + + * you want to publish source packages as well as git branches + +Not every option is covered here. dgit(1) has a mostly-complete list +of config options, although not always with useful descriptions. + +You will need to choose a DISTRO name for your distro. This should be +stable; globally unique; preferably not contain full stops or +underscores; and preferably be lowercase. + +You will also need: + + * Software to manage a Debian-format archive, suitable for use + by apt (including apt-get source). I suggest reprepro. + This guide will not help you much with setting up reprepro. + + * A git server. It must accessible push by ssh, and by anonymous + internet users (by the git https smart protocol, preferably; + failing that, git:// or plain http might do, although they + leave your dgit users vulnerable). + + There are various options for the git server, depending on how much + you trust your uploaders. There are four levels of trust and + sophistication: + + shell account + + For use when uploaders have shell accounts on the server and you + trust them completely. You then do not need to install any special + software on the server. + + dgit-repos-server + + Your uploaders do not (necessarily) have shell accounts. + You will need to collect their ssh keys and also their PGP + signing keys. You can restrict uploads on a per-package + per-key basis by using the Debian `dm.txt' format. + + dgit-repos-server + policy hook + + You want to impose additional policy. For example, Debian's + copyright review process means that uploads of new packages are + initially not public: dgit-repos-policy-debian is an example. + + custom implementation + + From the dgit client's point of view, the dgit git server is a git + server accessed by ssh (when pushing) or https (when fetching). + You may use anything that has the right properties for your needs. + dgit primarily authenticates pushes by signing tags, so your + software will probably need to check and verify that tag + appropriately before accepting a push. dgit-repos-server knows how + to do this properly. + +Set up your git server, as follows: + + shell account + + Make a suitable (sub)directory. You should create a _template.git + bare repo, with appropriate permissions. When new packages are + uploaded, this _template.git will be copied. You will probably + want to set core.sharedRepository in the template, and/or arrange + for personal groups and 002 umask. + + dgit-repos-server + + Additionally, install dgit-infrastructure. Create a service + account `dgit' on the server. For each authorised uploader, put + their ssh key in dgit's authorized_keys file, with a + restricted_command specifying the dgit-repos-server invocation. + Put the keyring where dgit-repos-server can find it. + Consult the comment at the top of dgit-repos-server for the + restricted command rune. + +You should set the following global (or user) git config options: + + dgit-distro.DISTRO.git-url + dgit-distro.DISTRO.git-url-suffix + Specifies the publicly accessible git URLs for your + dgit git server. The urls generated are + + The url should be stable. + + dgit-distro.DISTRO/push.git-url "" + dgit-distro.DISTRO/push.git-host + FQDN of your git server's ssh interface + + dgit-distro.DISTRO/push.git-user-force + Set to `dgit' if you are not using `shell account' mode + dgit-distro.DISTRO/push.username + Each user's username on the server, when using `shell + account' mode. + + dgit-distro.DISTRO/push.git-proto "git+ssh://" + dgit-distro.DISTRO/push.git-path "/dgit/DISTRO/repos" + (Or in shell account mode, whereever your repos are.) + + dgit-distro.DISTRO.git-check "true" + dgit-distro.DISTRO.git-check-suffix "/info/refs" + This works with cgit. What's needed is a way to construct a URL + which will retrieve some object if the repo exists on the server, + or give 404 otherwise. The urls are + + + dgit-distro.DISTRO/push.git-check "ssh-cmd" + + dgit-distro.DISTRO/push.git-create "ssh-cmd" + For shell account mode + dgit-distro.DISTRO/push.git-create "true" + For dgit-repos-server + + dgit-distro.DISTRO.upload-host + What "host" value to pass to dput, to upload. + +dgit clients need to access your archive as well as the dgit git +server. This enables them to see which packages are actually "in your +archive". + +When they download source packages, they use a mirror: + dgit-distro.DISTRO.mirror "https://ftp.example.com" +(data from mirrors is verified using pgp, so plain http is OK; +https is better for privacy.) + +You should ideally provide some kind of API to enable dgit clients to +rapidly find information about a specific package. For example, DAK +(the Debian Archive Kit) as used by Debian provides the ftpmaster API at + https://api.ftp-master.debian.org/ + +If you do this, then you can set: + dgit-distro.DISTRO.archive-query "ftpmasterapi:" + dgit-distro.DISTRO.archive-query-url", "https://ftpapi.example.com/" + +dgit can fall back to using the Packages files, like apt does. +This is often slower because clients must download information +about the whole distro even though dgit only wants one package +(at a time, anyway). (There is some cacheing.) To use this, +specify + dgit-distro.DISTRO.archive-query "aptget:" +and it will find the data from the specified mirror. In this case you +will need to make sure your local apt has the appropriate keys so +that it can verify the release signatures from the mirror. + -- 2.30.2