From e4b972f3c82dbe4b5e363e48ed01d97cc060a2c0 Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Wed, 15 Jun 2016 16:29:52 -0400 Subject: update `README.md` --- README.md | 105 ++++++++++++++++++++++++++++++++++---------------------------- 1 file changed, 58 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index 58e3bc0..824e74d 100644 --- a/README.md +++ b/README.md @@ -1,65 +1,76 @@ -This repository contains 4 things: +This repository contains tools for working with hackers.git +information. - 1. Information about Parabola contributors - 2. `Makefile` and `bin/`: tools for working with that information - 3. `misc/git-shell-commands`: for use with git-shell - 4. `misc/git-hooks`: git hooks +The most important 4 programs are: -Honestly, the latter two probably don't belong, but they've always -been in this repository, so I didn't want to just delete them. If you -remove git-shell-hooks in the future, be warned that -/srv/git/git-shell-commands is currently a symlink to there; you'll -want to change that. + - `meta-check`: sanity-check hackers.git data + - `ssh-list-authorized-keys`: configure sshd to use this for + AuthorizedKeysCommand to have it get SSH keys directly from + hackers.git + - `postfix-generate-virtual-map`: generate a virtual map + for Postfix that provides email aliases for users in hackers.git + - `pacman-make-keyring` generate a tarball with the pacman-keyring + files for the users in hackers.git -Adding users -============ +The others are: -Users ("hackers") are added by creating a file in the `users/` -directory. The file should be named `users/${UID}.yml` where UID is -the numeric POSIX user ID for that user. See -`bin/meta-normalize-stdio` for a listing of all the properties you can -put in the users file; or look at the existing files as examples. + - `meta-normalize-stdio`: used by `meta-check` + - `meta-cat`: used by `nshd` + - `pgp-list-keyids`: used by `pacman-make-keyring` + - `uid-map`: used by `pacman-make-keyring` -To add a profile image of a user, add it to the `dev-imgs/` folder. +Each of the programs looks for `parabola-hackers.yml` in he current +directory (except for `meta-normalize-stdio`, which has no +configuration). -Images in `dev-imgs/`: - - MUST be named `${username}.png` - - SHOULD be 125x125 px - - SHOULD be run through pngcrush +# Configuration -The files in `bin/` are configured with `cfg_*` variables at the top -of each file. +The main two things programs at are `yamldir` which tells them where +to find `hackers.git/users`, and `groupgroups` which augments the +`groups` array for each user. -Using the tools (make) -====================== +## pacman-make-keyring -There are 4 `make` targets of interest: `pacman-keyring`, `dist`, -`upload` and `postfix-virtual-map`. `make [all]` makes `pacman-keyring` -and`postfix-virtual-map`. The output goes in -`output/{pacman-keyring,postfix-virtual-map}` respectively. +`pacman-make-keyring` also looks at `keyring_cachedir` to see where to +store files that can be cached between versions of the keyring. -`pacman-keyring` makes the Pacman keyring that we package up as the -`parabola-keyring` package. +## ssh-list-authorized-keys -`dist` makes the `parabola-keyring` tarball. +`ssh-list-authorized-keys` also looks at `ssh_pseudo_users`. +System users (`/etc/passwd`) mentioned in this variable may be SSH'ed +into by hackers.git users who are in a group of the same name. -`upload` makes the uploading of `parabola-keyring` tarball to the server. +## nshd (TODO) -`postfix-virtual-map` makes a map for postfix email aliases we provide -to our developers. +`nshd` also looks at `pam_password_prohibit_message` to decide what to +say when prohibiting a user from being changed via PAM. -Using the tools (scripts) -========================= +# Usage -Most of the scripts assume that the current directory is the root of -this repository. +## meta-check -The most important 3 scripts are: +Just run it, it will report any problems with hackers.git data. - - `meta-check`: sanity-check the user data - - `meta-normalize-stdio`: normalize a user YAML file - - `ssh-list-authorized-keys`: configure sshd to use this for - AuthorizedKeysCommand to have it get SSH keys directly from the - user data here +## ssh-list-authorized-keys + +Configure `sshd_config:AuthorizedKeysCommand` to be this program. +`sshd` will run it as `ssh-list-authorized-keys ${USERNAME}` + +## postfix-generate-virtual-map + + postfix-show-virtual-map > /etc/postfix/virtual-parabola.nu + postmap hash:/etc/postfix/virtual-parabola.nu + +## pacman-make-keyring + + pacman-make-keyring V=$(date -u +%Y%m%d) + scp parabola-keyring-$(date -u +%Y%m%d).tar.gz repo.parabola.nu:/srv/repo/main/other/parabola-keyring/ + +or + + cd $(. "$(librelib conf)" && load_files makepkg && echo "$SRCDEST") + pacman-make-keyring V=$(date -u +%Y%m%d) -The others are all used by `make`. +In the latter case, it would get uploaded automagically by +`librerelease` when you release a parabola-keyring with the matching +version. -- cgit v1.2.2