James Moger
2014-05-12 edeab95cac16e5f17cfcd75a9969d8708bf360ab
commit | author | age
22957a 1
JM 2 ## Using the SSH transport
3
4 *SINCE 1.5.0*
5
6 The SSH transport is a very exciting improvement to Gitblit.  Aside from offering a simple password-less, public key workflow the SSH transport also allows exposes a new approach to interacting with Gitblit: SSH commands.  The Gerrit and Android projects have to be thanked for providing great base SSH code that Gitblit has integrated.
7
edeab9 8 You may watch an Asciinema screencast of using the SSH transport and it's command infrastructure [here](https://asciinema.org/a/9342).
JM 9
22957a 10 ### Cloning & Pushing
JM 11
12 By default, Gitblit serves the SSH transport on port 29418, which is the same as Gerrit.  Why was 29418 chosen?  It's likely because it resembles the IANA port assigned to the git protocol (9418).
13
14 Gitblit will authenticate using username/password or public keys.
15
16     git clone ssh://<username>@<hostname>:29418/myrepository.git
17
18 ### Setting up your account to use public key authentication
19
20 Public key authentication allows you to operate in a password-less workflow and to separate your web login credentials from your git credentials.  Setting up public key authentication is very simple.  If you are working on Windows you'll need to install [Git for Windows](http://git-scm.com/download/win).
21
22 First you'll need to create an SSH key pair, if you don't already have one or if you want to generate a new, separate key.
23
24     ssh-keygen
25
26 Then you can upload your *public* key right from the command-line.
27
413e9b 28     cat ~/.ssh/id_rsa.pub | ssh -l <username> -p 29418 <hostname> keys add
JM 29     cat c:\<userfolder>\.ssh\id_rsa.pub | ssh -l <username> -p 29418 <hostname> keys add
22957a 30
JM 31 **NOTE:** It is important to note that *ssh-keygen* generates a public/private keypair (e.g. id_rsa and id_rsa.pub).  You want to upload the *public* key, which is denoted by the *.pub* file extension.
32
33 Once you've done both of those steps you should be able to execute the following command without a password prompt.
34
617909 35     ssh -l <username> -p 29418 <hostname>
22957a 36
JM 37 ### Setting up an SSH alias
38
39 Typing the following command syntax all the time gets to be rather tedious.
40
413e9b 41     ssh -l <username> -p 29418 <hostname>
22957a 42
JM 43 You can define an alias for your server which will reduce your command syntax to something like this.
44
617909 45     ssh <alias>
22957a 46
JM 47 Create or modify your `~/.ssh/config` file and add a host entry.  If you are on Windows, you'll want to create or modify `<userfolder>\.ssh\config`, where *userfolder* is dependent on your version of Windows.  Most recently this is `c:\users\<userfolder>`.
48
49     Host <alias>
50         IdentityFile ~/.ssh/id_rsa
51         User <username>
52         Port 29418
53         HostName <hostname>
54
55 ### SSH Commands
56
eec333 57 Gitblit supports SSH command plugins and provides several commands out-of-the-box.
22957a 58
413e9b 59 #### keys
22957a 60
413e9b 61 The *keys* command dispatcher allows you to manage your public ssh keys.  You can list keys, add keys, remove keys, and identify the key in-use for the active session.
22957a 62
eec333 63 ##### keys add
22957a 64
JM 65 Add an SSH public key to your account.  This command accepts a public key piped to stdin.
66
413e9b 67     cat ~/.ssh/id_rsa.pub | ssh -l <username> -p 29418 <hostname> keys add
617909 68
JM 69 ##### keys list
70
71 Show the SSH public keys you have added to your account.
72
413e9b 73     ssh -l <username> -p 29418 <hostname> keys list
22957a 74
eec333 75 ##### keys remove
22957a 76
617909 77 Remove an SSH public key from your account.  This command accepts several input values, the most useful one is an index number which matches the index number displayed in the `list` command.
22957a 78
413e9b 79     ssh -l <username> -p 29418 <hostname> keys remove 2
22957a 80
JM 81 You can also remove all your public keys from your account.
82
413e9b 83     ssh -l <username> -p 29418 <hostname> keys remove ALL
JM 84
2d73a0 85 ##### keys permission
413e9b 86
2d73a0 87 You may control the access permission for each SSH key.  This is more of a safety feature than a security measure.
JM 88
89 | Permission | Description                                     |
90 | ---------- | ----------------------------------------------- |
91 | V          | SSH key may not be used for clone/fetch or push |
92 | R          | SSH key may be used to clone/fetch              |
93 | RW         | SSH key may be used to clone/fetch and push     |
94
edeab9 95 ### Mac OSX Fonts
JM 96
97 Many of Gitblit's SSH commands rely on ANSI border characters to provide a pretty presentation of data.  Unfortunately, the fonts provided by Apple - while very nice - don't work well with ANSI border characters.  The following public domain fixed-width, fixed-point, bitmapped fonts work very nicely.  I find the 6x12 font with a line spacing of ~0.8 to be quite acceptable.
98
99 [6x12.dfont](6x12.dfont)
100 [6x13.dfont](6x13.dfont)
101 [7x13.dfont](7x13.dfont)
102 [7x14.dfont](7x14.dfont)
22957a 103