deac/gitolite
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

doc/6: rename the file, change focus completely

Browse source
This commit is contained in:
Sitaram Chamarty 2009-11-03 14:01:03 +05:30 committed by Sitaram Chamarty
parent 33305ed8e7
commit 8aecaa2da2
2 changed files with 95 additions and 40 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

129
doc/6-complex-ssh-setups.mkd → doc/6-ssh-troubleshooting.mkd
View file

@ -1,15 +1,17 @@
# more complex ssh setups
# ssh troubleshooting
What do you need to know in order to create more complex ssh setups (for
instance if you have *two* gitolite servers you are administering)? Once more
unto the breach, here's more ssh magic!
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:
* files on client
* ssh sanity checks
* explanation
* files on the server
* sanity checks
* files on client
* more complex ssh setups
* two gitolite servers to manage?
* further reading
----
@ -18,31 +20,61 @@ In this document:
> shell and gitolite access, so he has **two** pubkeys in play.
> 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
> `~/.ssh/config` stuff, and their repo urls are very simple, like:
> `git@my.git.server:reponame.git`.
> 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`.
----
### files on client
### ssh sanity checks
* default keypair; used to get shell access to servers. You would have
copied this pubkey to the gitolite server in order to log in without a
password. (On Linux systems you may have used `ssh-copy-id` to do that).
You would have done this *before* you ran the easy install script, because
otherwise easy install won't run!
There are two quick sanity checks you can run:
~/.ssh/id_rsa
~/.ssh/id_rsa.pub
* running `ssh gitolite` should get you a list of repos you have rights to
access, as described [here][myrights]
* gitolite keypair; the "sitaram" in this is the 3rd argument to the
`src/00-easy-install.sh` command you ran; the easy install script does the
rest
[myrights]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd#myrights
~/.ssh/sitaram
~/.ssh/sitaram.pub
* conversely, `ssh git@server` should get you a command line
### files on the server
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
Here's how it all hangs together.
#### files on the server
* the authkeys file; this contains one line containing the pubkey of each
user who is permitted to login without a password.
@ -72,12 +104,30 @@ In this document:
argument `sitaram`. This is how gitolite is invoked, (and is told the
user logging in is "sitaram").
#### files on client
* default keypair; used to get shell access to servers. You would have
copied this pubkey to the gitolite server in order to log in without a
password. (On Linux systems you may have used `ssh-copy-id` to do that).
You would have done this *before* you ran the easy install script, because
otherwise easy install won't run!
~/.ssh/id_rsa
~/.ssh/id_rsa.pub
* gitolite keypair; the "sitaram" in this is the 3rd argument to the
`src/00-easy-install.sh` command you ran; the easy install script does the
rest
~/.ssh/sitaram
~/.ssh/sitaram.pub
* config file; this file has an entry for gitolite access:
~/.ssh/config
Let's step back a bit. Normally, you might expect to access gitolite
repos like this:
To understand why we need that, let's step back a bit. Normally, you
might expect to access gitolite repos like this:
ssh://git@server/reponame.git
@ -87,7 +137,7 @@ In this document:
control will work.
You need to force ssh to use the *other* keypair when performing a git
operation. With just ssh, that would be
operation. With normal ssh, that would be
ssh -i ~/.ssh/sitaram git@server
@ -103,8 +153,8 @@ In this document:
hostname server
identityfile ~/.ssh/sitaram
(The "gitolite" can be anything you want of course; it's like an alias for
all the stuff below it). This ensures that typing
(The "gitolite" can be anything you want of course; it's like a group name
for all the stuff below it). This ensures that typing
ssh gitolite
@ -119,17 +169,12 @@ In this document:
now works as expected, invoking the special keypair instead of the default
one.
### sanity checks
### more complex ssh setups
* `ssh gitolite` should get you the `SSH_ORIGINAL_COMMAND` error. If you
get a command line, something is wrong
What do you need to know in order to create more complex ssh setups (for
instance if you have *two* gitolite servers you are administering)?
* conversely, `ssh git@server` should get you a command line
* the "origin" URL in any clones should look like `gitolite:reponame.git`
instead of something more complex
### two gitolite servers to manage?
#### two gitolite servers to manage?
* they can have the same key; no harm there (example, sitaram.pub)
@ -146,3 +191,13 @@ In this document:
hostname server2
identityfile ~/.ssh/sitaram
* now access one server's repos as `gitolite:reponame.git` and the other
server's repos as `gitolite2:reponame.git`.
### further reading
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.
[glb]: http://sitaramc.github.com/0-installing/9-gitolite-basics.html#IMPORTANT_overview_of_ssh

2
src/00-easy-install.sh
View file

@ -446,7 +446,7 @@ CONFIG FILE FORMAT: see comments in conf/example.conf in the gitolite source.
SSH MAGIC: Remember you (the admin) now have *two* keys to access the server
hosting your gitolite setup -- one to get you a command line, and one to get
you gitolite access; see doc/6-complex-ssh-setups.mkd. If you're not using
you gitolite access; see doc/6-ssh-troubleshooting.mkd. If you're not using
keychain or some such software, you may have to run this each time you log in:
ssh-add ~/.ssh/$admin_name