HgLogin is a system designed by MarkSchaefer for [[SharedSSH]].  Have a look at the alternatives described there before deciding to use this system.

    '''Note:''' The following instructions describe the very personal setup we
    use on our system. I decided to add this page because the configuration
    described here a) works for Mercurial out of the box and b) solves some
    problems from [(Link broken) http://www.kitenet.net/~joey/sshcvs/]: In particular, it
    allows distinguishing multiple committers and a (crude) form of permissions.
    It is most probably neither the best nor the most elegant way and I don't
    promise anything more than that it works for me.
    --- MarcSchaefer

== Setting up the shared SSH account for hg-login ==

The first step is creating a dedicated user on the server side -- let's call
it ''mercurial''. Nobody should be able to log into this account with a
password, so set the password field in the /etc/passwd (or /etc/shadow) to *. It needs a valid
shell though, since sshd always calls scripts through the shell. Then, copy
the ''hg-login'' script at the end of this page into the home directory
and create a directory ''repositories'', which will contain (wait for it)
the repositories (duh).

Note that everybody with read/write permissions to the ''repository'' directory
can read/write to the repositories directly, so you might want to prevent
that.

== Allowing connections from a user ==

Every user needs his own public/private key (see the manpage of ''ssh-keygen''
for how to create one). Append the generated public key to ''~mercurial/.ssh/authorized_keys''
on the server side, prefixed with some options to grant access to mercurial only.
More precisely, every line has to look like this:

{{{
command="/home/mercurial/hg-login [user]",no-port-forwarding,no-X11-forwarding,no-agent-forwarding ssh-[type] [key]
}}}

Here ''[user]'' is an identifier which will later be used for granting
access to a repository, ''[type]'' is dsa or rsa depending on the key type
and ''[key]'' is the key itself, followed by an optional comment.

On every connect, the user must be able to present the corresponding
private key, for example by adding it to his ssh-agent.

== Creating repositories and setting permissions ==

Creating a shared repository is simple: Just initialise it in ''repositories''
like every other repository. However, nobody will be able to access it unless
you grant them permission. To allow a user to access the repository
''~mercurial/repositories/<repos>'', create a file
''~mercurial/repositories/<repos>.allow''
which contains his username (the one from ''authorized_keys'') alone on a line.

Note that it is not possible to only grant read rights -- it's full access
or nothing.

== Using shared access ==

Now you can connect to the repository by giving an ordinary hg command with server address and repository name, for example

{{{
hg clone ssh://mercurial@hg.example.com/<repos>
}}}

== The hg-login script ==

The following is a (Perl) script (sorry ;) ) to mediate the access to the
shared repositories. It first of all checks the supplied username and the
command that is to be executed for sanity (usernames must be alphanumeric,
starting with a letter), then normalises and checks the repository path
(creating subdirectories in ''repositories'' is allowed, but file names
must match ^[a-zA-Z0-9][a-zA-Z0-9-:+.]$). Only if these checks pass
and the desired repository exists and allows access by the user, the
server process is started.

{{{
#!/usr/bin/perl -w -T
use strict;

$ENV{PATH} = '/usr/local/bin:/usr/bin:/bin';

my $hg = '/usr/local/bin/hg';
my $repositories = '/home/mercurial/repositories';

# The following character classes describe the allowed user-
# and repository names. Note that we forbid all path constituents
# which begin with a dot -- look ma, no directory traversal.

my $r_user = qr#[a-zA-Z][a-zA-Z0-9]*#;
my $r_file = qr#[a-zA-Z0-9][a-zA-Z0-9-:+._]*#;

# The username is given as the first argument (from command=
# in authorized_keys), sshd is kind enough to pass the requested
# command as an environment variable.

my $user_in = $ARGV[0];
my $cmd_in  = $ENV{SSH_ORIGINAL_COMMAND} || '';

# First, basic sanity checking on the username. The assignment
# is necessary to convince Perl that the username is no longer
# tainted.

defined $user_in
    or die "No username given.\n";
my ($user) = $user_in =~ /^($r_user)$/
    or die "Invalid username `$user_in'.\n";

# The command passed by hg has a very specific structure: Check that.

my ($repos) = $cmd_in =~ m#^hg -R (\S+) serve --stdio$#
    or die "Invalid command `$cmd_in' requested.\n";

# Now for the repository path: We assume that it consists of $r_files
# separated by slashes. Leading and trailing ones are ignored.

s#^/+##, s#/+$##, s#/+#/#g for $repos;

my $path = '';
foreach my $file_in (split m#/#, $repos) {
    my ($file) = $file_in =~ /^($r_file)$/
        or die "Invalid repository path `$repos'";
    $path .= "/$file";
}

# Only the toplevel-directory of every Mercurial repository contains
# a subdir `.hg'.

-d "$repositories/$path/.hg" or die "No such repository `$path'.\n";

# Now for permissions ...

open my $perms, '<', "$repositories/$path.allow"
    or die "No such repository `$path'.\n";

chomp( my @allowed_in = <$perms> );

close $perms;

my $allowed = '';
$user eq $_ and $allowed = 1 for @allowed_in;
$allowed or die "You are not listed in the $path.allow file. Access denied.\n";

# Ok, everything is in order: go for it.

exec $hg, '-R', "$repositories/$path", 'serve', '--stdio';
die "Unable to exec `hg' on repository `$path' ($!)\n";
}}}

== Extending above to allow read only access for some ==

Using a hook and slightly extending above, you can implement read only access for some users. Change

{{{
$user eq $_ and $allowed = 1 for @allowed_in;
}}}

to

{{{
my $allowed = '';
for (@allowed_in) {
  if ($user eq $_) {
    $allowed = 1;
    $ENV{READ_WRITE} = 1;
    last;
  } elsif ("${user}.ro" eq $_) {
    $allowed = 1;
    $ENV{READ_ONLY} = 1;
    last;
  }
}
}}}

Then add a hook via {{{.hgrc}}} like so...

{{{
[hooks]
pretxnchangegroup.deny.lock = /path/to/lock_script
}}}

Where {{{lock_script}}} is a simple shell script like

{{{
#!/bin/ksh
if [[ "x${READ_ONLY}" != "x" ]]; then
  print "You do not have write access." 1>&2
  exit 1
fi
exit 0
}}}

Now any users in the {{{allow}}} file above specified like
{{{
someuser.ro
}}}
will have read only access while others will have read write access.

== Further enhancement to allow even finer grained control ==

The above can be further extended to add

{{{
# allow more control via hooks
$ENV{SSH_HG_USER} = $user;
}}}

just before

{{{
exec $hg, '-R', "$repositories/$path", 'serve', '--stdio';
}}}

By doing so, the hooks can make use of the {{{SSH_HG_USER}}} env. variable and make even more fine grained access control decisions e.g.

{{{
#!/bin/ksh
if [[ "x${SSH_HG_USER}" == "xmpm" ]]; then
   print "Allowing access to mpm" 1>&2
else
   print "You are not mpm. Access denied." 1>&2
   exit 1
fi
exit 0
}}}