This page must be read in full the first time. If you start from some nicelooking section in the middle it may not help you unless you're already anexpert at ssh.
This page should help you troubleshoot ssh-related problems in installing andaccessing gitolite. It also has a section of random ssh-related tips andtricks that gitolite can do.
Ssh-keygen is the basic way for generating keys for such kind of authentication. I will also explain how to maintain those keys by changing their associated comments and more importantly by changing the passphrases using this handy utility. Generating Keys. Generating public keys for authentication is the basic and most often used feature of. Then I looked up on the internet and found that I had to generate an ssh key for my account on GitHub. However, upon doing so, when I tried to do ssh-keygen -t rsa '[email protected]' it simply said ssh-keygen is not recognized. I tried doing mkdir C: ssh but that didn't work. If it helps I'm using Ruby Rails and I'm on a Windows computer.
caveats
- Before reading this page, it is mandatory to read and completely understandthis, which is a very detailed look at how gitolite uses ssh's features on the server side. Don't assume you know all that; if you did, you wouldn't be needing this page either!
- This page, and others linked from this, together comprise all the help I can give you in terms of the ssh aspect of using gitolite. If you're installing gitolite, you're a 'system admin', like it or not. Ssh is therefore a necessary skill. Please take the time to learn at least enough to get passwordless access working.
- Please note that authentication is not really gitolite's job at all. I'd rather spend time on actual gitolite features, code, and documentation than authentication (i.e., ssh, in the common case).Surprised? This might help explain better.
naming conventions used
- Your workstation is the client. Your userid on the client does not matter, and it has no relation to your gitolite username.
- The server is called server and the 'hosting user' is git. If this is an RPM/DEB install, the hosting user is probably called 'gitolite', however we will use 'git' in this page.
taking stock -- relevant files and directories
- The client has a
~/.ssh
containing a few keypairs. It may also have aconfig
file. - The client also has a clone of the 'gitolite-admin' repo, which contains a bunch of
*.pub
files inkeydir
. We assume this clone is in$HOME
Cardiolife defibrillator manual. ; if it is not, adjust instructions accordingly when needed. - The git user on the server has a
~/.ssh/authorized_keys
file that the ssh daemon uses to authenticate incoming users. We often call this file authkeys to save typing, and it always means the one on the server (we're not interested in this file on the client side). - The server also has a
~/.gitolite/keydir
which contains a bunch of*.pub
files.
normal gitolite key handling
Here's how normal gitolite key handling works:
- (On client) pub key changes like adding new ones, deleting old ones, etc., are done in the
keydir
directory in the gitolite-admin repo clone. Then the admingit add
s andgit commit
s those changes, thengit push
es them to the server. - (On server) a successful push from the client makes git invoke the post-update hook in the gitolite-admin repo. This hook is installed by gitolite, and it does a bunch of things which are quite transparent to the admin, but we'll describe briefly here:
- The pubkey files from this push are checked-out into
~/.gitolite/keydir
(and similarly the config files into~/.gitolite/conf
). - The 'compile' script then runs, which uses these files to populate
~/.ssh/authorized_keys
on the server.The authkeys file may have other, (non-gitolite) keys also. Thoselines are preserved. Gitolite only touches lines that are foundbetween gitolite's 'marker' lines (# gitolite start
and# gitolite end
).
Since I'm pretty sure at least some of you didn't bother to read the'IMPORTANT: PLEASE READ FIRST' section above, let me take a minute to pointyou there again. Especially the first bullet.
Done? OK, read on.
The following problem(s) indicate that pubkey access is not working at all, soyou should start with appendix 1. If that doesn't fix the problem, continuewith the other appendices in sequence.
- Running any git clone/fetch/ls-remote or just
ssh git@server info
asks you for a password. (Or, if your sshd is set to use keys only, it just disconnects without doing anything).
The following problem(s) indicate that your pubkey is bypassing gitolite andgoing straight to a shell. You should start with appendix 2and continue with the rest in sequence. Appendix 5 has somebackground info.
- Running
ssh git@server info
gets you the output of the GNU 'info' command instead of gitolite's version and access info. - Running
git clone git@server:repositories/reponame
(note presence ofrepositories/
in URL) works.Parallels for mac exit coherence. [A proper gitolite key will only let yougit clone git@server:reponame
(note absence ofrepositories/
)] - You are able to clone repositories but are unable to push changes back (the error complains about the
GL_BINDIR
environment variable not being set or about not being able to locateGitolite/Hooks/Update.pm
, and thehooks/update
failing in some way).[If you rungit remote -v
you will find that your clone URL included therepositories/
described above!] - Conversely, using the correct syntax,
git clone git@server:reponame
(note absence ofrepositories/
in the URL), gets youfatal: 'reponame' does not appear to be a git repository
, and yet you are sure 'reponame' exists, you haven't mis-spelled it, etc.
Since I'm pretty sure at least some of you didn't bother to read the'IMPORTANT: PLEASE READ FIRST' section above, let me take a minute to pointyou there again. Especially the first bullet.
Done? OK, now the general outline for ssh troubleshooting is this:
- Make sure the server's overall setup even allows pubkey based login. I.e., check that git fetch/clone/ls-remote commands or a plain
ssh git@server info
do NOT ask for a password. If you do get asked for a password, see appendix 1. - Match client-side pubkeys (
~/.ssh/*.pub
) with the server's authkeys file. To do this, runsshkeys-lint
, which tells you in detail what key has what access. See appendix 2. - At this point, we know that we have the right key, and that if sshd receives that key, things will work. But we're not done yet. We still need to make sure that this specific key is being offered/sent by the client, instead of the default key. See appendix 3 and appendix 4.
giving shell access to gitolite users
Thanks to an idea from Jesse Keating, a single key can allow both gitoliteaccess and shell access.
(v3.6.1+) There are two ways to do this, both require uncommentingand editing the 'Shell' line in the ENABLE list in the rc file.
If you have only a few users who need to get shell access, edit the line tolook like this (note the trailing comma!): Free accident reconstruction software mac.
If you have lots of users, add them to some file accessible to gitolite, (oneper line, no extra whitespace), then specify the full path of the file. Forexample:
(Note in this case we have to use double quotes since we are using a variablethat needs to be interpolated into the value).
Then run
gitolite compile; gitolite trigger POST_COMPILE
or push a dummychange to the admin repo.the SHELL_USERS_LIST
If you're using gitolite v3.6 or below, it's slightly different. You have toenable the trigger by uncommenting the 'Shell' line in the ENABLE list, butyou cannot list the users directly on the 'Shell' line in the rc file, nor canyou put the file name on that line. Instead, you have to go to the variablessection in the rc file and set the SHELL_USERS_LIST variable to thefilename. For example:
Then run
gitolite compile; gitolite trigger POST_COMPILE
or push a dummychange to the admin repo.NOTE: to maintain backward compatibility, this method will continue towork in 3.6.*, but when 3.7 is released (whenever that may be), it will notwork, and you will have to use the new syntax described above.
distinguishing one key from another
Since a user can have more than one key, it is sometimes usefulto distinguish one key from another. Sshd does not tell you even thefingerprint of the key that finally matched, so normally all you have is the
GL_USER
env var.However, if you replace
![Ssh Keygen G3 Ssh Keygen G3](https://image.slidesharecdn.com/secureshellperformancetesting-170525153133/95/secure-shell-performance-testing-49-638.jpg?cb=1495968874)
in the ENABLE list with
then an extra argument is added after the username in the 'command' variableof the authkeys file. That is, instead of this:
you get this:
You can then write an INPUT trigger to do whatever you need with the filename, which is in
$ARGV[1]
(the second argument). The actual file isavailable at $ENV{GL_ADMIN_BASE}/$ARGV[1]
if you need its contents.simulating ssh-copy-id
don't have
ssh-copy-id
? This is broadly what that command does, if you wantto replicate it manually. The input is your pubkey, typically~/.ssh/id_rsa.pub
from your client/workstation.- It copies it to the server as some file.
- It appends that file to
~/.ssh/authorized_keys
on the server (creating it if it doesn't already exist). - Code 300 32 sdr downloads. It then makes sure that all these files/directories have go-w perms set (assuming user is 'git'):
[Actually,
sshd
requires that even directories above~
(/
, /home
,typically) also must be go-w
, but that needs root. And typicallythey're already set that way anyway. (Or if they're not, you've gotbigger problems than gitolite install not working!)]problems with using non-openssh public keys
Boeing tool and equipment manual. Gitolite accepts public keys only in openssh format. Trying to use an 'ssh2'key (used by proprietary SSH software) will not be a happy experience.src/triggers/post-compile/ssh-authkeys can be made to detect non-opensshformats and automatically convert them; patches welcome!
The actual conversion command, if you want to just do it manually for now andbe done with it, is:
then use the resulting pubkey as you normally would in gitolite.
windows issues
On windows, I have only used msysgit, and the openssh that comes with it.Over time, I have grown to distrust putty/plink due to the number of peoplewho seem to have trouble when those beasts are involved (I myself have neverused them for any kind of git access). If you have unusual ssh problems thatjust don't seem to have any explanation, try removing all traces ofputty/plink, including environment variables, etc., and then try again.
Thankfully, someone contributed this.
![Ssh Keygen G3 Ssh Keygen G3](https://www.ssh.com/manuals/server-admin/61/clientserver-directorystructure.png)
NOTE: This section should be useful to anyone trying to get password-less access working. It is not necessarily specific to gitolite, so keep that in mind if the wording feels a little more general than you were expecting.
You have generated a keypair on your workstation (
ssh-keygen
) and copied thepublic part of it (~/.ssh/id_rsa.pub
, by default) to the server.On the server you have appended this file to
~/.ssh/authorized_keys
. Or youran something, like the gitolite setup
step during a gitolite install, whichshould have done that for you.You now expect to log in without having to type in a password, but when youtry, you are being asked for a password.
This is a quick checklist:
- Make sure you're being asked for a password and not a passphrase. Do not confuse or mistake a prompt saying
Enter passphrase for key '/home/sitaram/.ssh/id_rsa':
for a password prompt from the remote server!When you create an ssh keypair usingssh-keygen
, you have the option ofprotecting it with a passphrase. When you subsequently use that keypairto access a remote host, your local ssh client needs to unlock thecorresponding private key, and ssh will probably ask for the passphraseyou set when you created the keypair.You have two choices to avoid this prompt every time you try to use theprivate key. The first is to create keypairs without a passphrase (justhit enter when prompted for one). Be sure to add a passphrase later,once everything is working, usingssh-keygen -p
.The second is to usessh-agent
(orkeychain
, which in turn usesssh-agent
) or something like that to manage your keys. Other thandiscussing one more potential trouble-spot with ssh-agent (see below),further discussion of ssh-agent/keychain is out of scope of this page. - Ssh is very sensitive to permissions. An extremely conservative setup is given below, but be sure to do this on both the client and the server:
- Actually, every component of the path to
~/.ssh/authorized_keys
all the way upto the root directory must be at leastchmod go-w
. So be sure to check/
and/home
also. - While you're doing this, make sure the owner and group info for each of these components are correct.
ls -ald ~ ~/.ssh ~/.ssh/authorized_keys
will tell you what they are. - You may also want to check
/etc/ssh/sshd_config
to see if the 'git' user is allowed to login at all. For example, if that file contains anAllowUsers
config entry, then only users mentioned in that line are allowed to log in! - While you're in there, check that file does NOT have a setting for
AuthorizedKeysFile
. Seeman sshd_config
for details. This setting is a show stopper for gitolite to use ssh. - Some OSs/distributions require that the 'git' user should have a password and/or not be a locked account. You may want to check that as well.
- If your server is running SELinux, and you install gitolite to
/var/gitolite
or another location unsupported by default SELinux policies, then SELinux will prevent sshd from reading.ssh/authorized_keys
. Consider installing gitolite to/var/lib/gitolite
, which is a supported location by default SELinux policies. - If all that fails, log onto the server as root,
cd /var/log
, and look for a file calledauth.log
orsecure
or some such name. Look inside this file for messages matching the approximate time of your last attempt to login, to see if they tell you what is the problem.
The sshkeys-lint program can be run on the server or the client. Run it with'-h' to get a help message.
On the server you can run
gitolite sshkeys-lint
and it will tell you, foreach key in the admin directory's keydir, what access is available. This isespecially good at finding duplicate keys and such.To run it on the client you have to copy the file src/commands/sshkeys-lintfrom some gitolite clone, then follow these steps:
- Get a copy of
~/.ssh/authorized_keys
from the server and put it in/tmp/foo
or something. - cd to
~/.ssh
. - Run
/path/to/sshkeys-lint *.pub < /tmp/foo
.
Note that it is not trying to log in or anything -- it's just comparingfingerprints as computed by
ssh-keygen -l
.If the pubkey file you're interested in appears to have the correct access tothe server, you're done with this step.
Otherwise you have to rename some keypairs and try again to get the effect youneed. Be careful:
- Do not just rename the '.pub' file; you will have to rename the corresponding private key also (the one with the same basename but without an extension).
- If you're running ssh-agent, you may have to delete (using
ssh-add -D
) and re-add identities for it to pick up the renamed ones correctly.
typical cause(s)
The admin often has passwordless shell access to
git@server
already, andthen used that same key to get access to gitolite (i.e., copied that samepubkey as YourName.pub and ran gitolite setup
on it).As a result, the same key appears twice in the authkeys file now, and sincethe ssh server will always use the first match, the second occurrence (whichinvokes gitolite) is ignored.
To fix this, you have to use a different keypair for gitolite access. Thebest way to do this is to create a new keypair, copy the pubkey to the serveras YourName.pub, then run
gitolite setup -pk YourName.pub
on the server.Remember to adjust your agent identities using ssh-add -D and ssh-add ifyou're using ssh-agent, otherwise these new keys may not work.- Make sure the right private key is being offered. Run ssh in very verbose mode and look for the word 'Offering', like so:If some keys are being offered, but not the key that was supposed to beused, you may be using ssh-agent (next bullet). You may also need tocreate some host aliases in
~/.ssh/config
(appendix 4). - (ssh-agent issues) If
ssh-add -l
responds with either 'The agent has no identities.' or 'Could not open a connection to your authentication agent.', then you can skip this bullet.However, ifssh-add -l
lists any keys at all, then something weirdhappens. Due to a quirk in ssh-agent, ssh will now only use one ofthose keys, even if you explicitly ask for some other key to be used.In that case, add the key you want usingssh-add ~/.ssh/YourName
and trythe access again.
(or 'making git use the right options for ssh')
The ssh command has several options for non-default items to be specified.Two common examples are
-p
for the port number if it is not 22, and -i
forthe public key file if you do not want to use just ~/.ssh/id_rsa
or such.Git has two ssh-based URL syntaxes, but neither allows specifying anon-default public key file. And a port number is only allowed in one ofthem. (See
man git-clone
for details). Finally, hosts often have to bereferred with IP addresses (such is life), or the name is very long, or hardto remember.Using a 'host' para in
~/.ssh/config
lets you nicely encapsulate all thiswithin ssh and give it a short, easy-to-remember, name. Example:Now you can simply use the one word
gitolite
(which is the host alias wedefined here) and ssh will infer all those details defined under it -- justsay ssh gitolite
and git clone gitolite:reponame
and things will work.(By the way, the 'port' and 'identityfile' lines are needed only if you havenon-default values, although I put them in anyway just to be complete).
more than one keypair
If you have more than one pubkey with access to the same server, youmust use this method to make git pick up the right key. There is no otherway to do this, as far as I know.
A typical example would be if you wanted shell access to the gitolite serverusing one keypair, and gitolite-mediated access using another. Here's how Ido that, where my 'id_rsa' keypair has shell access, and my 'sitaram' keypairhas gitolite access:
Then I would use 'ssh gitolite-sh' to get a command line, and use the hostalias 'gitolite' in git clone and other commands, as well as for gitolitecommands (like 'ssh gitolite info').
Just to be clear, please note that this assumes the authorized keys file onthe gitolite hosting user has my 'id_rsa.pub' line, without the gitoliterelated forced command and options.
When you bypass gitolite, you end up running your normal shell instead of thespecial gitolite entry point script
gitolite-shell
.This means commands (like 'info') are interpreted by the shell instead ofgitolite.
It also means git operations look for repos in
$HOME
.However, gitolite places all your repos in
~/repositories
, and internallyprefixes this before calling the actual git command you invoked. Thus, thepathname of the repo that you use on the client is almost never the correctpathname on the server. (This is by design. Don't argue.)Ssh-keygen-g3 Convert To Openssh
This means that, you get 2 kinds of errors if you bypass gitolite
Ssh Keygen Github
- When you use
git@server:reponame
with a key that bypasses gitolite (i.e., gets you a shell), this prefixing does not happen, and so the repo is not found. Neither a clone/fetch nor a push will work. - Conversely, consider
git@server:repositories/reponame.git
. The clone operation will work -- you're using the full Unix path, and so the shell finds the repo where you said it would be. However, when you push, gitolite's update hook kicks in, and fails to run because some of the environment variables it is expecting are not present.