README
author Paul Crowley <paul@ciphergoth.org>
Thu, 24 Apr 2008 08:27:30 +0100
changeset 28 583ed103e021
parent 26 2c4f499ea12f
child 30 98dbde5b13a1
permissions -rw-r--r--
update README to reflect new scripted installer
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
13
1206ed37090a more README fixes
Paul Crowley <paul@ciphergoth.org>
parents: 12
diff changeset
     1
hg-admin-tools
2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
     2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
     3
A set of tools for managing authorization and access control for
12
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
     4
ssh-based Mercurial repositories
2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
     5
12
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
     6
Paul Crowley, paul@lshift.net, 2008
2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
     7
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
     8
This software may be used and distributed according to the terms
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
     9
of the GNU General Public License, incorporated herein by reference.
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    10
12
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    11
WHAT IT GIVES YOU
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    12
14
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    13
These tools make it easier to provide a centralized repository host
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    14
with read/write access to many repositories for many developers.
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    15
Access control is managed with a special repository on the server
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    16
called "hgadmin"; pushes to this repository immediately change the
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    17
rules that are in effect.
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    18
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    19
Inside "hgadmin" is a "keys" directory containing the SSH keys of all
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    20
developers who have access, and a file "hg-ssh-access.conf" which
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    21
gives a set of rules defining who can do what to what.
12
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    22
14
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    23
All of the repositories controlled by these tools are owned by a
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    24
single user (the "hg" user in what follows), but many remote users can
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    25
act on them.  We don't use file permissions to achieve that - instead,
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    26
developers log in as the "hg" user when they connect to the repository
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    27
host using ssh, using ssh URLs of the form
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    28
"ssh://hg@repository-host/repository-name".  A restricted shell
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    29
prevents them from using this access for unauthorized purposes.
12
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    30
Developers are authenticated only using SSH keys; no other form of
28
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
    31
authentication is supported.
12
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    32
28
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
    33
QUICK START
12
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    34
28
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
    35
You will need 
2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    36
28
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
    37
- "sudo" installed
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
    38
- "sudo" root privileges
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
    39
- an ssh-key set up with ssh-agent
2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    40
28
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
    41
Ensure there is no user called "hg" on the repository host, and run
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
    42
"./install" to create them. You are now the sole user able to change
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
    43
and create repositories on this repository host.  To give access to
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
    44
others, check out hgadmin - as yourself, and on whichever host is most
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
    45
convenient, but using the ssh-key with which you set up the
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
    46
repository:
2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    47
12
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    48
   mkdir ~/hg
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    49
   cd ~/hg
14
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    50
   hg clone ssh://hg@repository-host/hgadmin
12
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    51
   cd hgadmin
2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    52
10
524b4a45ef0a wrap overlong lines
Paul Crowley <paul@lshift.net>
parents: 4
diff changeset
    53
You can now add other users by putting their keys in an appropriate
524b4a45ef0a wrap overlong lines
Paul Crowley <paul@lshift.net>
parents: 4
diff changeset
    54
subdirectory of the "keys" directory, and control their access by
524b4a45ef0a wrap overlong lines
Paul Crowley <paul@lshift.net>
parents: 4
diff changeset
    55
editing hg-ssh-access.conf.  Changes will take effect as soon as you
14
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    56
push them to "ssh://hg@repository-host/hgadmin".
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    57
18
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
    58
Users authorized to do so can now also create new repositories on this
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
    59
host with "clone":
14
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    60
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    61
  hg clone . ssh://hg@repository-host/my-project-name
13
1206ed37090a more README fixes
Paul Crowley <paul@ciphergoth.org>
parents: 12
diff changeset
    62
1206ed37090a more README fixes
Paul Crowley <paul@ciphergoth.org>
parents: 12
diff changeset
    63
HG-SSH-ACCESS.CONF
2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    64
10
524b4a45ef0a wrap overlong lines
Paul Crowley <paul@lshift.net>
parents: 4
diff changeset
    65
Each line of hg-ssh-access.conf has the following syntax:
2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    66
18
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
    67
<rule> <condition> <condition> ...
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
    68
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
    69
Rule is one of
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
    70
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
    71
init - allow any operation, including the creation of new repositories
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
    72
write - allow reads and writes to this file in this repository
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
    73
read - allow the repo to be read but reject matching writes
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
    74
deny - deny all requests
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
    75
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
    76
A condition is a globpattern matched against a relative path, one of:
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
    77
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
    78
user=<globpattern> - user's key
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
    79
repo=<globpattern> - repo (as the user supplies it)
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
    80
file=<globpattern> - file in the repo
20
f4daa224dc7e Add support for locking by branch, and document breaking in.
Paul Crowley <paul@ciphergoth.org>
parents: 18
diff changeset
    81
branch=<globpattern> - name of the branch
18
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
    82
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
    83
The first rule in the file which has all its conditions satisfied is
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
    84
used to determine whether an action is allowed.
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
    85
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
    86
Paths cannot contain any special characters except "/"; glob patterns
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
    87
cannot contain any special characters except "/" and "*".  "*" matches
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
    88
zero or more characters not including "/" while "**" matches zero or
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
    89
more characters including "/".
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
    90
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
    91
Blank lines and lines that start with "#" are ignored.
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
    92
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
    93
FILE CONDITIONS
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
    94
20
f4daa224dc7e Add support for locking by branch, and document breaking in.
Paul Crowley <paul@ciphergoth.org>
parents: 18
diff changeset
    95
The rules file is used to make four decisions:
2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    96
18
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
    97
- Whether to allow a repository to be created
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
    98
- Whether to allow access to a repository
20
f4daa224dc7e Add support for locking by branch, and document breaking in.
Paul Crowley <paul@ciphergoth.org>
parents: 18
diff changeset
    99
- Whether to allow a changeset on a particular branch at all
18
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   100
- Whether to allow a changeset to change a particular file
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   101
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   102
When the first two of these decisions are being made, nothing is known
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   103
about what files might be changed, and so all file conditions
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   104
automatically succeed for the purpose of such decisions.  This means
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   105
that doing tricky things with file conditions can have
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   106
counterintuitive consequences:
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   107
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   108
- You cannot limit read access to a subset of a repository with a
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   109
"read" rule and a file condition: any user who has access to a
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   110
repository can read all of it and its full history.  Such a rule can
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   111
only have the effect of masking a later "write" rule, as in this
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   112
example:
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   113
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   114
   read repo=specialrepo file=dontwritethis
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   115
   write repo=specialrepo
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   116
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   117
allows all users to read specialrepo, and to write to all files
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   118
*except* that any changeset which writes to "dontwritethis" will be
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   119
rejected.
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   120
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   121
- For similar reasons, don't give "init" rules file conditions.
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   122
26
2c4f499ea12f Explain limitations of branch/file rule combination
Paul Crowley <paul@lshift.net>
parents: 20
diff changeset
   123
- Don't try to deny write access to a particular file on a particular
2c4f499ea12f Explain limitations of branch/file rule combination
Paul Crowley <paul@lshift.net>
parents: 20
diff changeset
   124
branch - a developer can write to the file on another branch and then
2c4f499ea12f Explain limitations of branch/file rule combination
Paul Crowley <paul@lshift.net>
parents: 20
diff changeset
   125
merge it in.  Either deny all writes to the branch from that user, or
2c4f499ea12f Explain limitations of branch/file rule combination
Paul Crowley <paul@lshift.net>
parents: 20
diff changeset
   126
allow them to write to all the files they can write to on any branch.
2c4f499ea12f Explain limitations of branch/file rule combination
Paul Crowley <paul@lshift.net>
parents: 20
diff changeset
   127
In other words, something like this will have the intended effect
2c4f499ea12f Explain limitations of branch/file rule combination
Paul Crowley <paul@lshift.net>
parents: 20
diff changeset
   128
2c4f499ea12f Explain limitations of branch/file rule combination
Paul Crowley <paul@lshift.net>
parents: 20
diff changeset
   129
  write user=docs/* branch=docs file=docs/*
2c4f499ea12f Explain limitations of branch/file rule combination
Paul Crowley <paul@lshift.net>
parents: 20
diff changeset
   130
2c4f499ea12f Explain limitations of branch/file rule combination
Paul Crowley <paul@lshift.net>
parents: 20
diff changeset
   131
But something like this will not have the intended effect; it will
2c4f499ea12f Explain limitations of branch/file rule combination
Paul Crowley <paul@lshift.net>
parents: 20
diff changeset
   132
effectively allow these users to write to any file on any branch, by
2c4f499ea12f Explain limitations of branch/file rule combination
Paul Crowley <paul@lshift.net>
parents: 20
diff changeset
   133
writing it to "docs" first:
2c4f499ea12f Explain limitations of branch/file rule combination
Paul Crowley <paul@lshift.net>
parents: 20
diff changeset
   134
2c4f499ea12f Explain limitations of branch/file rule combination
Paul Crowley <paul@lshift.net>
parents: 20
diff changeset
   135
  write user=docs/* branch=docs
2c4f499ea12f Explain limitations of branch/file rule combination
Paul Crowley <paul@lshift.net>
parents: 20
diff changeset
   136
  write user=docs/* file=docs/*
2c4f499ea12f Explain limitations of branch/file rule combination
Paul Crowley <paul@lshift.net>
parents: 20
diff changeset
   137
  read user=docs/*
2c4f499ea12f Explain limitations of branch/file rule combination
Paul Crowley <paul@lshift.net>
parents: 20
diff changeset
   138
28
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
   139
HOW IT WORKS
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
   140
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
   141
When a developer attempts to connect to a repository via ssh, the SSH
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
   142
daemon searches for a match for that user's key in
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
   143
~hg/.ssh/authorized_keys.  If the developer is authorised to connect
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
   144
to the repository they will have an entry in this file.  The entry
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
   145
includes a "command" prefix which specifies that the restricted shell
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
   146
should be used; this shell is passed an argument identifying the
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
   147
developer.  The shell parses the command the developer is trying to
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
   148
execute, and consults a rules file to see if that developer is allowed
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
   149
to perform that action on that repository.  The bulk of the work of
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
   150
the restricted shell is done by the Python program "hg-ssh", but the
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
   151
shell script "hg-ssh-wrapper" sets up some configuration so that you
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
   152
can change it to suit your local installation.
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
   153
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
   154
The file ~hg/.ssh/authorized_keys is generated by "refresh-auth",
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
   155
which recurses through a directory of files containing SSH keys and
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
   156
generates an entry in authorized_keys for each one, using the name of
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
   157
the key file as the identifier for the developer.  These keys will
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
   158
live in the "keys" subdirectory of a repository called "hgadmin".  A
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
   159
hook in this repository re-runs "refresh-auth" on the most recent
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
   160
version after every push.
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
   161
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
   162
Finally, a hook in an extension is run for each changeset that is
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
   163
remotely committed, which uses the rules file to determine whether to
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
   164
allow the changeset.
583ed103e021 update README to reflect new scripted installer
Paul Crowley <paul@ciphergoth.org>
parents: 26
diff changeset
   165
20
f4daa224dc7e Add support for locking by branch, and document breaking in.
Paul Crowley <paul@ciphergoth.org>
parents: 18
diff changeset
   166
LOCKING YOURSELF OUT
f4daa224dc7e Add support for locking by branch, and document breaking in.
Paul Crowley <paul@ciphergoth.org>
parents: 18
diff changeset
   167
f4daa224dc7e Add support for locking by branch, and document breaking in.
Paul Crowley <paul@ciphergoth.org>
parents: 18
diff changeset
   168
If you find yourself "locked out" - that is, that you no longer have
f4daa224dc7e Add support for locking by branch, and document breaking in.
Paul Crowley <paul@ciphergoth.org>
parents: 18
diff changeset
   169
the permissions needed in hgadmin - you can break back in again if
f4daa224dc7e Add support for locking by branch, and document breaking in.
Paul Crowley <paul@ciphergoth.org>
parents: 18
diff changeset
   170
you're able to become the "hg" user on the repository host.  Once you
f4daa224dc7e Add support for locking by branch, and document breaking in.
Paul Crowley <paul@ciphergoth.org>
parents: 18
diff changeset
   171
are that user, delete ~hg/.ssh/authorized_keys (to stop any user who
f4daa224dc7e Add support for locking by branch, and document breaking in.
Paul Crowley <paul@ciphergoth.org>
parents: 18
diff changeset
   172
might have access but shouldn't from using the repository while you
f4daa224dc7e Add support for locking by branch, and document breaking in.
Paul Crowley <paul@ciphergoth.org>
parents: 18
diff changeset
   173
fix things).  Then go into ~hg/repos/hgadmin, do an "hg update", edit
f4daa224dc7e Add support for locking by branch, and document breaking in.
Paul Crowley <paul@ciphergoth.org>
parents: 18
diff changeset
   174
things to your satisfaction, and commit the change.  Finally, run
f4daa224dc7e Add support for locking by branch, and document breaking in.
Paul Crowley <paul@ciphergoth.org>
parents: 18
diff changeset
   175
~/admin/hg-admin-tools/refresh-auth to regenerate
f4daa224dc7e Add support for locking by branch, and document breaking in.
Paul Crowley <paul@ciphergoth.org>
parents: 18
diff changeset
   176
~hg/.ssh/authorized_keys. 
f4daa224dc7e Add support for locking by branch, and document breaking in.
Paul Crowley <paul@ciphergoth.org>
parents: 18
diff changeset
   177
18
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   178
THANKS
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   179
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   180
Thanks for reading this far.  If you use hg-admin-tools, please tell
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   181
me about it.
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   182
538d6b198f4a Big change to support file conditions; format of hg-ssh-access.conf
Paul Crowley <paul@lshift.net>
parents: 15
diff changeset
   183
Paul Crowley, 2008