doc/6 revamp; would appreciate reviews ;-)
This commit is contained in:
Sitaram Chamarty
parent
645ab77af5
commit
e68d76f127
|
|
@ -471,7 +471,7 @@ etc. You'd just like a simple way to know what repos you have access to.
|
|||
Easy! Just use ssh and try to log in as if you were attempting to get a
|
||||
shell:
|
||||
|
||||
$ ssh gitolite
|
||||
$ ssh gitolite info
|
||||
PTY allocation request failed on channel 0
|
||||
hello sitaram, the gitolite version here is v0.6-17-g94ed189
|
||||
you have the following permissions:
|
||||
|
|
|
|||
|
|
@ -1,116 +1,175 @@
|
|||
# ssh troubleshooting
|
||||
|
||||
Update 2009-12-23: most of this document is now of historical interest and
|
||||
will be totally revamped when I have time. For now, just note this amendment.
|
||||
|
||||
The document below says "we can't use the same key for both [gitolite access
|
||||
and shell access]...". We've managed (thanks to an idea from Jesse Keating)
|
||||
to get around this. Now it *is* possible for a single key to allow both
|
||||
gitolite access *and* shell access.
|
||||
|
||||
This is done by:
|
||||
|
||||
* (**on the server**) listing all such users in a variable called
|
||||
`$SHELL_USERS` in the `~/.gitolite.rc` file. For example:
|
||||
|
||||
$SHELL_USERS = "alice bob";
|
||||
|
||||
(Note the syntax: a space separated list of users in one string variable).
|
||||
|
||||
* (**on your client**) make at least a dummy change to your clone of the
|
||||
gitolite-admin repo and push it.
|
||||
|
||||
**IMPORTANT UPGRADE NOTE**: a previous implementation of this feature worked
|
||||
by adding people to a special group (`@SHELL`) in the *config* file. This
|
||||
meant that anyone with gitolite-admin repo write access could add himself to
|
||||
the `@SHELL` group and push, thus obtaining shell.
|
||||
|
||||
This is not a problem for most setups, but if someone wants to separate these
|
||||
two privileges (the right to push the admin repo and the right to get a shell)
|
||||
then it does pose a problem. Since the "rc" file can only be edited by
|
||||
someone who already has shell access, we now use that instead, even though
|
||||
this forces a change in the syntax.
|
||||
|
||||
To migrate from the old scheme to the new one, add a new variable
|
||||
`$SHELL_USERS` to `~/.gitolite.rc` on the server with the appropriate names in
|
||||
it. **It is best to do this directly on the server *before* upgrading to this
|
||||
version.** (After the upgrade is done and tested you can remove the `@SHELL`
|
||||
lines from the gitolite config file).
|
||||
|
||||
----
|
||||
|
||||
Ssh has always been the biggest troublespot in all this. While gitolite makes
|
||||
it as easy as possible, you might still run into trouble sometimes.
|
||||
|
||||
In this document:
|
||||
|
||||
* ssh sanity checks
|
||||
* explanation
|
||||
* basic ssh troubleshooting
|
||||
* passphrases versus passwords
|
||||
* ssh-agent problems
|
||||
* basic ssh troubleshooting for the main admin
|
||||
* basic ssh troubleshooting for a normal user
|
||||
* details
|
||||
* files on the server
|
||||
* files on client
|
||||
* why two keys on client
|
||||
* more complex ssh setups
|
||||
* two gitolite servers to manage?
|
||||
* further reading
|
||||
* giving shell access to gitolite users
|
||||
|
||||
----
|
||||
|
||||
> But before we get to all that, let's clarify that all this is applicable
|
||||
> **only** to the gitolite **admin**. He's the only one who needs both a
|
||||
> shell and gitolite access, so he has **two** pubkeys in play.
|
||||
This document should help you troubleshoot ssh-related problems in accessing
|
||||
gitolite *after* the install has completed successfully.
|
||||
|
||||
> Normal users have only one pubkey, since they are only allowed to access
|
||||
> gitolite itself. They do not need to worry about any of this stuff, and
|
||||
> their repo urls are very simple, like: `git@my.git.server:reponame.git`.
|
||||
In addition, I **strongly** recommend reading [this document][glb] -- it's a
|
||||
very detailed look at how gitolite uses ssh's features on the server side.
|
||||
Most people don't know ssh as well as they *think* they do; even if you dont
|
||||
have any problems right now, it's worth skimming over.
|
||||
|
||||
----
|
||||
Please also note that ssh problems don't always look like ssh problems. One
|
||||
common example: when the remote says the repo you're trying to access "does
|
||||
not appear to be a git repository", and yet you are sure it exists, you
|
||||
haven't mis-spelled it, etc.
|
||||
|
||||
### ssh sanity checks
|
||||
### basic ssh troubleshooting
|
||||
|
||||
There are two quick sanity checks you can run:
|
||||
[glb]: http://sitaramc.github.com/0-installing/9-gitolite-basics.html#IMPORTANT_overview_of_ssh
|
||||
|
||||
* running `ssh gitolite` should get you a list of repos you have rights to
|
||||
access, as described [here][myrights]
|
||||
I assume the gitolite server is called "server" and the user hosting all the
|
||||
gitolite repos is "git". I will also be using "sitaram" as the *gitolite
|
||||
username* of the admin.
|
||||
|
||||
Unless specifically mentioned, all these commands are run on the user's or
|
||||
admin's workstation, not on the server.
|
||||
|
||||
#### passphrases versus passwords
|
||||
|
||||
When you create an ssh keypair, you have the option of protecting it with a
|
||||
passphrase. When you subsequently use that keypair to access a remote host,
|
||||
your *local* ssh client needs to unlock the corresponding private key, and ssh
|
||||
will probably ask for the passphrase you set when you created the keypair.
|
||||
|
||||
Do not confuse or mistake this prompt (`Enter passphrase for key
|
||||
'/home/sitaram/.ssh/id_rsa':`) for a password prompt from the remote server!
|
||||
|
||||
You have two choices to avoid this prompt every time you try to access the
|
||||
remote. The first is to create keypairs *without* a passphrase (just hit
|
||||
enter when prompted for one). **Be sure to add a passphrase later, once
|
||||
everything is working, using `ssh-keygen -p`**.
|
||||
|
||||
The second is to use `ssh-agent` (or `keychain`, which in turn uses
|
||||
`ssh-agent`) or something like that to manage your keys. Other than the next
|
||||
section, further discussion of this is out of scope of this document.
|
||||
|
||||
#### ssh-agent problems
|
||||
|
||||
1. Run `ssh-add -l`. If this responds with either "The agent has no
|
||||
identities." or "Could not open a connection to your authentication
|
||||
agent.", skip this section.
|
||||
|
||||
2. However, if it lists some keys, like this:
|
||||
|
||||
2048 fc:c1:48:1e:06:31:97:a4:8b:fc:37:b2:76:14:c7:53 /home/sitaram/.ssh/id_rsa (RSA)
|
||||
2048 d2:e0:7f:fa:1a:89:22:41:bb:06:d9:ff:a7:27:36:5c /home/sitaram/.ssh/sitaram (RSA)
|
||||
|
||||
then run `ls ~/.ssh` and make sure that all the keypairs you have there
|
||||
are represented in the `ssh-add -l` output.
|
||||
|
||||
3. If you find any keypairs in `~/.ssh` that are not represented in the
|
||||
`ssh-add -l` output, add them. For instance, if `ssh-add -l` showed me
|
||||
only the `id_rsa` key, but I also had a `sitaram` (and `sitaram.pub`)
|
||||
keypair, I'd run `ssh-add ~/.ssh/sitaram` to add it.
|
||||
|
||||
This is because ssh-agent has a quirk: if `ssh-add -l` shows *any* keys at
|
||||
all, ssh will only use those keys. Even if you explicitly specify an unlisted
|
||||
key using `ssh -i` or an `identityfile` directive in the config file, it won't
|
||||
use it.
|
||||
|
||||
#### basic ssh troubleshooting for the main admin
|
||||
|
||||
You're the "main admin" if you're trying to access gitolite from the same
|
||||
workstation and user account where you ran the "easy install" command. You
|
||||
should have two keypairs in your `~/.ssh` directory. The pair called `id_rsa`
|
||||
(and `id_rsa.pub`) was probably the first one you created, and you used this
|
||||
to get passwordless (pubkey based) access to the server (which was a
|
||||
pre-requisite for running the easy install command).
|
||||
|
||||
The second keypair has the same name as the last argument in the easy install
|
||||
command you ran (in my case, `sitaram` and `sitaram.pub`). It was probably
|
||||
created by the easy install script, and is the key used for gitolite access.
|
||||
|
||||
In addition, you should have a "gitolite" paragraph in your `~/.ssh/config`,
|
||||
looking something like this:
|
||||
|
||||
host gitolite
|
||||
user git
|
||||
hostname server
|
||||
identityfile ~/.ssh/sitaram
|
||||
|
||||
If any of these are not true, you did something funky in your install; email
|
||||
me or hop onto #git and hope for the best ;-)
|
||||
|
||||
Otherwise, run these checks:
|
||||
|
||||
1. `ssh git@server` should get you a command line.
|
||||
|
||||
If it asks you for a password, then your `id_rsa` keypair changed after
|
||||
you ran the easy install, or someone fiddled with the
|
||||
`~/.ssh/authorized_keys` file on the server.
|
||||
|
||||
If it prints [gitolite version and access info][myrights], you managed to
|
||||
overwrite the `id_rsa` keypair with the `sitaram` keypair, or something
|
||||
equally weird.
|
||||
|
||||
2. `ssh gitolite info` should print some [gitolite version and access
|
||||
info][myrights]. If you get the output of the GNU info command instead,
|
||||
you probably reused your `id_rsa` keypair as your `sitaram` keypair, or
|
||||
overwrote the `sitaram` keypair with the `id_rsa` keypair.
|
||||
|
||||
There are many ways to fix this, depending on where and what the damage is.
|
||||
The most generic way (and therefore time-taking) is to re-install gitolite
|
||||
from scratch:
|
||||
|
||||
* make a backup of your gitolite-admin repo clone somewhere (basically your
|
||||
"keydir/*.pub" and your "conf/gitolite.conf"). If necessary get these
|
||||
files from the server's `~/.gitolite` directory.
|
||||
* log on to the server somehow (using some other account, using a password,
|
||||
su-ing in, etc) and delete `~/.ssh/authorized_keys`. Rename or move aside
|
||||
`~/.gitolite` so that also looks like it is missing.
|
||||
* back on your workstation, make sure you have 2 keypairs (`id_rsa` and
|
||||
`sitaram`, along with corresponding `.pub` files). Create them if needed.
|
||||
Also make sure they are *different* and not a copy of each other :-)
|
||||
* install gitolite normally:
|
||||
* run `ssh-copy-id -i ~/.ssh/id_rsa git@server` to get passwordless
|
||||
access to the server. (Mac users may have to do this step manually)
|
||||
* make sure `ssh git@server pwd` prints the `$HOME` of `git@server`
|
||||
**without** asking for a password. Do not proceed till this works.
|
||||
* run easy install again, (in my case: `cd gitolite-source;
|
||||
src/gl-easy-install -q git server sitaram`)
|
||||
* go to your gitolite-admin repo clone, and copy `conf/gitolite.conf` and
|
||||
`keydir/*.pub` from your backup to this directory
|
||||
* copy (be sure to overwrite!) `~/.ssh/sitaram.pub` also to keydir
|
||||
* now `git add keydir; git commit; git push -f`
|
||||
|
||||
That's a long sequence but it should work.
|
||||
|
||||
#### basic ssh troubleshooting for a normal user
|
||||
|
||||
For a normal user, life is much simpler. They should have only one pubkey,
|
||||
which was previously sent to the gitolite admin to add into the admin repo's
|
||||
`keydir` as "user.pub", and then "user" given permissions to some repo.
|
||||
|
||||
`ssh git@server info` should get you [gitolite version and access
|
||||
info][myrights]. If it asks you for a password, your pubkey was not sent to
|
||||
the server properly. Check with your admin.
|
||||
|
||||
[myrights]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd#myrights
|
||||
|
||||
* conversely, `ssh git@server` should get you a command line
|
||||
If it gets you the GNU info command output, you have shell access. This means
|
||||
you had command line access to the server *before* you were added as a
|
||||
gitolite user. If you send that same key to your gitolite admin to include in
|
||||
the admin repo, it won't work. For reasons why, see below.
|
||||
|
||||
If one or both of these does not work as expected, do this:
|
||||
|
||||
* first, check that your `~/.ssh` has two public keys, like below:
|
||||
|
||||
$ ls -al ~/.ssh/*.pub
|
||||
-rw-r--r-- 1 sitaram sitaram 409 2008-04-21 17:42 /home/sitaram/.ssh/id_rsa.pub
|
||||
-rw-r--r-- 1 sitaram sitaram 409 2009-10-15 16:25 /home/sitaram/.ssh/sitaram.pub
|
||||
|
||||
If it doesn't you have either lost your keys or you're on the wrong
|
||||
machine. As long as you have password access to the server you can alweys
|
||||
recover; just pretend you're installing from scratch and start over.
|
||||
|
||||
* next, try running `ssh-add -l`. On my desktop the output looks like this:
|
||||
|
||||
2048 63:ea:ab:10:d2:4f:88:f4:85:cb:d3:7d:3a:83:37:9a /home/sitaram/.ssh/id_rsa (RSA)
|
||||
2048 d7:23:89:12:5f:22:4f:ad:54:7d:7e:f8:f5:2a:e9:13 /home/sitaram/.ssh/sitaram (RSA)
|
||||
|
||||
If you get only one line (typically the top one), you should ssh-add the
|
||||
other one, using (in my case) `ssh-add ~/.ssh/sitaram`.
|
||||
|
||||
If you get no output, add both of them and check `ssh-add -l` again.
|
||||
|
||||
If this error keeps happening please consider installing [keychain][kch]
|
||||
or something similar, or add these commands to your bash startup scripts.
|
||||
|
||||
[kch]: http://www.gentoo.org/proj/en/keychain/
|
||||
|
||||
* Finally, make sure your `~/.ssh/config` has the required `host gitolite`
|
||||
para (see below for more on this).
|
||||
|
||||
Once these sanity checks have passed, things should be fine. However, if you
|
||||
still have problems, make sure that the "origin" URL in any clones looks like
|
||||
`gitolite:reponame.git`, not `git@server:reponame.git`.
|
||||
|
||||
### explanation
|
||||
### details
|
||||
|
||||
Here's how it all hangs together.
|
||||
|
||||
|
|
@ -301,10 +360,37 @@ instance if you have *two* gitolite servers you are administering)?
|
|||
* now access one server's repos as `gitolite:reponame.git` and the other
|
||||
server's repos as `gitolite2:reponame.git`.
|
||||
|
||||
### further reading
|
||||
### giving shell access to gitolite users
|
||||
|
||||
While this focused mostly on the client side ssh, you may also want to read
|
||||
[this][glb] for a much more detailed explanation of the ssh magic on the
|
||||
server side.
|
||||
We've managed (thanks to an idea from Jesse Keating) to make it possible for a
|
||||
single key to allow both gitolite access *and* shell access.
|
||||
|
||||
This is done by:
|
||||
|
||||
* (**on the server**) listing all such users in a variable called
|
||||
`$SHELL_USERS` in the `~/.gitolite.rc` file. For example:
|
||||
|
||||
$SHELL_USERS = "alice bob";
|
||||
|
||||
(Note the syntax: a space separated list of users in one string variable).
|
||||
|
||||
* (**on your client**) make at least a dummy change to your clone of the
|
||||
gitolite-admin repo and push it.
|
||||
|
||||
**IMPORTANT UPGRADE NOTE**: a previous implementation of this feature worked
|
||||
by adding people to a special group (`@SHELL`) in the *config* file. This
|
||||
meant that anyone with gitolite-admin repo write access could add himself to
|
||||
the `@SHELL` group and push, thus obtaining shell.
|
||||
|
||||
This is not a problem for most setups, but if someone wants to separate these
|
||||
two privileges (the right to push the admin repo and the right to get a shell)
|
||||
then it does pose a problem. Since the "rc" file can only be edited by
|
||||
someone who already has shell access, we now use that instead, even though
|
||||
this forces a change in the syntax.
|
||||
|
||||
To migrate from the old scheme to the new one, add a new variable
|
||||
`$SHELL_USERS` to `~/.gitolite.rc` on the server with the appropriate names in
|
||||
it. **It is best to do this directly on the server *before* upgrading to this
|
||||
version.** (After the upgrade is done and tested you can remove the `@SHELL`
|
||||
lines from the gitolite config file).
|
||||
|
||||
[glb]: http://sitaramc.github.com/0-installing/9-gitolite-basics.html#IMPORTANT_overview_of_ssh
|
||||
|
|
|
|||
Loading…
Reference in a new issue