From c6d49deb59c0d73a7fb459250aea974b0b01836f Mon Sep 17 00:00:00 2001 From: Daniel Kahn Gillmor Date: Tue, 2 Sep 2008 19:24:38 -0400 Subject: shipping getting-started docs directly; nevermind about calling them README. --- doc/README | 1 - doc/README.admin | 1 - 2 files changed, 2 deletions(-) delete mode 120000 doc/README delete mode 120000 doc/README.admin (limited to 'doc') diff --git a/doc/README b/doc/README deleted file mode 120000 index f6ea1dd..0000000 --- a/doc/README +++ /dev/null @@ -1 +0,0 @@ -../website/getting-started-user.mdwn \ No newline at end of file diff --git a/doc/README.admin b/doc/README.admin deleted file mode 120000 index dea47b6..0000000 --- a/doc/README.admin +++ /dev/null @@ -1 +0,0 @@ -../website/getting-started-admin.mdwn \ No newline at end of file -- cgit v1.2.3 From 4dfcb19ae2fed99d83e3e96a1a0aeafb7d06da61 Mon Sep 17 00:00:00 2001 From: Daniel Kahn Gillmor Date: Tue, 2 Sep 2008 19:36:18 -0400 Subject: stripped down, cleaned up MonkeySpec. --- doc/MonkeySpec | 154 ++++++++++++++------------------------------------------- 1 file changed, 37 insertions(+), 117 deletions(-) (limited to 'doc') diff --git a/doc/MonkeySpec b/doc/MonkeySpec index 54aaa72..66f44b0 100644 --- a/doc/MonkeySpec +++ b/doc/MonkeySpec @@ -1,59 +1,23 @@ THE MONKEYSPHERE ================ -AGENDA -====== -[x] clowning -[ ] work -[x] jrollins will talk and gesture - in progress - -MONKEYNAMES -=========== - -rhesus, marmoset, howler, langur, tamarin, barbary - -COMPONENTS -========== - -(names in "" are code names until we think of better ones.) - -common components ------------------ -* "rhesus": update known_hosts/authorized_keys files: - - be responsible for removing keys from the file as key revocation - happens - - be responsible for updating a key in the file where there is a key - replacement - - must result in a file that is parsable by the existing ssh client - without errors - - manual management must be allowed without stomping on it - - provide a simple, intelligible, clear policy for key acceptance - -* "langur": policy-editor for viewing/editing policies - -* gpg2ssh: utility to convert gpg keys to ssh - known_hosts/authorized_keys lines - -* ssh2gpg: create openpgp keypair from ssh keypair +Monkeysphere is authentication layer that allows the sysadmin to +perform authorization on OpenPGP user identities instead of on keys. +It also allows end users to authenticate/identify the ssh server they +are connecting to by checking the sysadmin's certification. -server-side components ----------------------- -* "howler": server gpg maintainer - - generate gpg keys for the server - - publish server gpg keys - - give owner trust to keys for user authentication +* GENERAL GOAL - use openpgp web-of-trust to authenticate ppl for SSH +* SPECIFIC GOAL - allow openssh to tie into pgp web-of-trust without + modifying the openpgp spec, gpg or openssh +* DESIGN GOALS - authentication, use the existing generic OpenSSH + client, the admin can make it default, although end-user should be + decide to use monkeysphere or not +* DESIGN GOAL - use of monkeysphere should not radically change + connecting-to-server experience -* "tamarin": concept - how to trigger or schedule rhesus at admin defined - points (e.g. via cron or during ssh connections). +Host identity piece of monkeysphere could be used without buying into +the user authentication component. -client-side components ----------------------- -* "marmoset": concept - how to trigger rhesus during attempt to initiate - connection to server - - runs on connection to a certain host - - triggers update to known_hosts file then makes connection - - proxy-command | pre-hook script | wrapper script - - (ssh_config "LocalCommand" is only run *after* connection) USE CASE ======== @@ -69,93 +33,49 @@ their personal gpg keys to the web of trust, and being good friends, have both signed each other's keys and marked each others keys with "full" ownertrust. -When Alice set up mangabey initially, she used howler to publish a gpg -key for the machine with the special userid of -"ssh://mangabey.example.org". She also signed mangabey's gpg key and -published this certification to commonly-used keyservers. Alice also -configured mangabey to treat her own key with full ownertrust (could -this be done as part of the howler invocation?) +When Alice set up mangabey initially, she published an OpenPGP key for +the machine with the special userid of "ssh://mangabey.example.org". +She also signed mangabey's OpenPGP key and published this +certification to commonly-used keyservers. Alice also configured +mangabey to treat her own key with full ownertrust, so that it knows +how to identify connecting users. Now, Alice creates a user account "bob" on mangabey, and puts Bob's userid ("Bob ") in the authorized_user_ids file for -user bob on mangabey. tamarin triggers on mangabey either by a -cronjob or an inotify hook, and invokes rhesus for the "bob" account. -rhesus automatically takes each userid in bob's authorized_user_ids -file, and looks on a keyserver to find all public keys associated with -that user ID, with the goal of populating the authorized_keys file for -bob@mangabey. +user bob on mangabey. The monkeysphere automatically (via cron or +inotify hook) takes each userid in bob's authorized_user_ids file, and +looks on a keyserver to find all public keys associated with that user +ID, with the goal of populating the authorized_keys file for +bob@mangabey. In particular: for each key found, the server evaluates the calculated validity of the specified user ID based on the ownertrust rules it has configured ("trust alice's certifications fully", in this example). For each key for which the user ID in question is fully-valid, it extracts all DSA- or RSA-based primary or secondary keys marked with -usage flags for encrypted communications and authentication, and -converts these gpg public keys into ssh public keys. Finally, rhesus -inserts these calculated public keys into the authorized_keys file for -bob. +the authentication usage flag, and converts these OpenPGP public keys +into ssh public keys. These keys are automatically placed into the +authorized_keys file for bob. Bob now attempts to connect, by firing up a terminal and invoking: "ssh bob@mangabey.example.org". Bob's monkeysphere-enabled ssh client notices that mangabey.example.org isn't already available in bob's -known_hosts file, and triggers rhesus (on Bob's computer) to fetch the -key for mangabey, with the goal of populating Bob's local known_hosts +known_hosts file, and fetches the host key for mangabey from the +public keyservers, with the goal of populating Bob's local known_hosts file. -In particular: rhesus queries its configured keyservers to find all -public keys with User ID ssh://mangabey.example.org. For each public -key found, rhesus checks the relevant User ID's validity, converts any -"encrypted comms, authentication" gpg public keys into ssh public keys -if the User ID validity is acceptable, and finally insert those keys -into Bob's known_hosts file. +In particular: the monkeysphere queries its configured keyservers to +find all public keys with User ID ssh://mangabey.example.org. For +each public key found, it checks the relevant User ID's validity, +converts any authentication-capable OpenPGP public keys into ssh +public keys if the User ID validity is acceptable, and finally insert +those keys into Bob's known_hosts file. On Bob's side, since mangabey's key had "full" validity (it was signed -by Alice whom he fully trusts), Bob's ssh client deems mangabey +by Alice, whom he fully trusts), Bob's ssh client deems mangabey "known" and no further host key checking is required. On mangabey's side, since Bob's key has "full" validity (it had been signed by Alice, mangabey's trusted administrator), Bob is authenticated and therefore authorized to log into his account. -NOTES -===== - -* Daniel and Elliot lie. -* We will use a distributed VCS, each developer will create their own - git repository and publish it publicly for others to pull from, mail - out -* public project page doesn't perhaps make sense yet -* approximate goal - using the web of trust to authenticate ppl for - SSH -* outline of various components of monkeysphere -* M: what does it mean to be in the monkeysphere? not necessarily a - great coder. -* J: interested in seeing project happen, not in actually doing it. - anybody can contribute as much as they want. -* J: if we put the structure in place to work on monkeysphere then we - don't have to do anything -* D: we are not creating -* understand gpg's keyring better, understanding tools better, - building scripts -* Some debian packages allow automated configuration of config files. - -* GENERAL GOAL - use openpgp web-of-trust to authenticate ppl for SSH -* SPECIFIC GOAL - allow openssh to tie into pgp web-of-trust without - modifying either openpgp and openssh -* DESIGN GOALS - authentication, use the existing generic OpenSSH - client, the admin can make it default, although end-user should be - decide to use monkeysphere or not -* DESIGN GOAL - use of monkeysphere should not radically change - connecting-to-server experience -* GOAL - pick a monkey-related name for each component - -Host identity piece of monkeysphere could be used without buying into -the authorization component. - -Monkeysphere is authentication layer that allows the sysadmin to -perform authorization on user identities instead of on keys, it -additionally allows the sysadmin also to authenticate the server to -the end-user. - -see doc/git-init for more detail on how to pull from the distributed -repositories. -- cgit v1.2.3 From 39ad3cccd2307fe3c43892376ab1a4e57b53b6d6 Mon Sep 17 00:00:00 2001 From: Jamie McClelland Date: Wed, 3 Sep 2008 12:27:18 -0400 Subject: adding sample ikiwiki setup file and mirrors web page. --- doc/ikiwiki.setup.sample | 29 ++++++++++++++++++++++++ website/mirrors.mdwn | 57 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 86 insertions(+) create mode 100644 doc/ikiwiki.setup.sample create mode 100644 website/mirrors.mdwn (limited to 'doc') diff --git a/doc/ikiwiki.setup.sample b/doc/ikiwiki.setup.sample new file mode 100644 index 0000000..97e77c8 --- /dev/null +++ b/doc/ikiwiki.setup.sample @@ -0,0 +1,29 @@ +use IkiWiki::Setup::Standard { + wikiname => "Monkeysphere", + adminemail => 'webmaster@monkeysphere.info', + + srcdir => "/path/to/cloned/monkeysphere/repo/website", + destdir => "/path/to/web/dir", + + url => "http://monkeysphere.info", + + rcs => "git", + + wrappers => [ + { + wrapper => "/path/to/post-receive/hook", + wrappermode => "0755", + } + ], + + rss => 1, + atom => 1, + verbose => 0, + syslog => 0, + + add_plugins => [qw{goodstuff favicon toc sidebar}], + + + tagbase => "tags", + +} diff --git a/website/mirrors.mdwn b/website/mirrors.mdwn new file mode 100644 index 0000000..8445a26 --- /dev/null +++ b/website/mirrors.mdwn @@ -0,0 +1,57 @@ +[[meta title="Mirroring the web site"]] + +In keeping with the philosophy of distributed development, our web site is +stored in our git repositories and converted into html by +[ikiwiki](http://ikiwiki.info/). + +We're mirrored on several servers. Rather than using ikiwiki's [pinger/pingee +approach to distribution](http://ikiwiki.info/tips/distributed_wikis/), we've +opted for a method that uses ssh. + +The steps for creating a new mirror are: + + * Add etch-backports to your /etc/apt/sources.list: + deb http://www.backports.org/debian etch-backports main contrib non-free + * Add the following lines to your /etc/apt/preferences file: + Package: ikiwiki + Pin: release a=etch-backports + Pin-Priority: 999 + + # needed by ikiwiki + Package: libcgi-formbuilder-perl + Pin: release a=etch-backports + Pin-Priority: 999 + + Package: git-core + Pin: release a=etch-backports + Pin-Priority: 999 + * Install git-core and ikiwiki + aptitude update; aptitutde install git-core ikiwiki + * Create a new user. Change the new users shell to git-shell: + adduser -s /usr/bin/git-shell + * Add webmaster@george's public key to this user's ~/.ssh/authorized_keys file + * Add web site configuration that the user has write access to. If you are using Apache, include the following rewrite: + RewriteEngine On + RewriteCond %{HTTP_HOST} !^(YOURHOSTNAME|web)\.monkeysphere\.info$ [NC] + RewriteCond %{HTTP_HOST} !^$ + RewriteRule ^/(.*) http://web.monkeysphere.info/$1 [L,R] + * Upload and edit ikiwiki.setup.sample from the docs directory + * As the new user, create two new git repos + mkdir monkeysphere.git; cd monkeysphere.git; git init --bare; cd ../ + git clone monkeysphere.git # this will create a second git repo called monkeysphere + * Change the mode of monkeysphere.git/hooks/post-receive to 755 + chmod 755 monkesphere.git/hooks/post-receive + * Edit the file so that it executes the post-receive hook ikiwiki generates (as you specified in the ikiwiki.setup file) + +The steps to be taken on the mirror site should now be complete. The following steps should be taken by a Monkeysphere admin user: + + * Add a new dns record for SERVERNAME.monkeysphere.info. + * Test the ssh connection by logging in as webmaster@george.riseup.net + * Add the new server as a remote on webmaster@george.riseup.net:monkeysphere.git + cd ~/monkeysphere.git + git add remote SERVERNAME USER@SERVERNAME.monkeysphere.info:/path/to/repo + * Test: + git pusch SERVERNAME + + + -- cgit v1.2.3