Gitblit devel
view | history | commit | commitdiff
Paul Martin
2016-04-30 a502d96a860456ec5e8c96761db70f7cabb74751
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
a5086d 26 **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.
JM 27
28 #### Uploading your public key from the command-line
29
22957a 30 Then you can upload your *public* key right from the command-line.
JM 31
413e9b 32     cat ~/.ssh/id_rsa.pub | ssh -l <username> -p 29418 <hostname> keys add
JM 33     cat c:\<userfolder>\.ssh\id_rsa.pub | ssh -l <username> -p 29418 <hostname> keys add
22957a 34
a5086d 35 #### Uploading your public key through the browser
22957a 36
a5086d 37 1. Navigate to your *profile* page from the dropdown user menu.
JM 38 2. Click the *SSH Keys* tab and paste your public key into the *Add SSH Key* form.
39 3. Click the *Save* button
40
41 Once you ave uploaded your public key you should be able to execute the following command without a password prompt.
22957a 42
617909 43     ssh -l <username> -p 29418 <hostname>
22957a 44
JM 45 ### Setting up an SSH alias
46
47 Typing the following command syntax all the time gets to be rather tedious.
48
413e9b 49     ssh -l <username> -p 29418 <hostname>
22957a 50
JM 51 You can define an alias for your server which will reduce your command syntax to something like this.
52
617909 53     ssh <alias>
22957a 54
JM 55 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>`.
56
57     Host <alias>
58         IdentityFile ~/.ssh/id_rsa
59         User <username>
60         Port 29418
61         HostName <hostname>
62
63 ### SSH Commands
64
eec333 65 Gitblit supports SSH command plugins and provides several commands out-of-the-box.
22957a 66
413e9b 67 #### keys
22957a 68
413e9b 69 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 70
eec333 71 ##### keys add
22957a 72
JM 73 Add an SSH public key to your account.  This command accepts a public key piped to stdin.
74
413e9b 75     cat ~/.ssh/id_rsa.pub | ssh -l <username> -p 29418 <hostname> keys add
617909 76
JM 77 ##### keys list
78
79 Show the SSH public keys you have added to your account.
80
413e9b 81     ssh -l <username> -p 29418 <hostname> keys list
22957a 82
eec333 83 ##### keys remove
22957a 84
617909 85 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 86
413e9b 87     ssh -l <username> -p 29418 <hostname> keys remove 2
22957a 88
JM 89 You can also remove all your public keys from your account.
90
413e9b 91     ssh -l <username> -p 29418 <hostname> keys remove ALL
JM 92
2d73a0 93 ##### keys permission
413e9b 94
2d73a0 95 You may control the access permission for each SSH key.  This is more of a safety feature than a security measure.
JM 96
97 | Permission | Description                                     |
98 | ---------- | ----------------------------------------------- |
99 | V          | SSH key may not be used for clone/fetch or push |
100 | R          | SSH key may be used to clone/fetch              |
101 | RW         | SSH key may be used to clone/fetch and push     |
102
edeab9 103 ### Mac OSX Fonts
JM 104
105 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.
106
107 [6x12.dfont](6x12.dfont)
108 [6x13.dfont](6x13.dfont)
109 [7x13.dfont](7x13.dfont)
110 [7x14.dfont](7x14.dfont)
22957a 111