From 22957a70fb7ba8a38564d6b6be15c661da0c3a20 Mon Sep 17 00:00:00 2001 From: James Moger <james.moger@gitblit.com> Date: Thu, 10 Apr 2014 18:58:08 -0400 Subject: [PATCH] Start SSH usage documentation --- src/site/setup_transport_ssh.mkd | 87 +++++++++++++++++++++++++++++++++++++++++++ build.xml | 14 ++++--- src/site/setup_transport_http.mkd | 6 +-- 3 files changed, 97 insertions(+), 10 deletions(-) diff --git a/build.xml b/build.xml index 32cb9f5..87f306a 100644 --- a/build.xml +++ b/build.xml @@ -561,9 +561,10 @@ <page name="Gitblit as a viewer" src="setup_viewer.mkd" /> </menu> <divider /> - <menu name="Client Configuration" pager="true" pagerPlacement="bottom" pagerLayout="justified"> - <page name="git client setup" src="setup_client.mkd" /> - <page name="eclipse plugin" src="eclipse_plugin.mkd" /> + <menu name="Client Usage" pager="true" pagerPlacement="bottom" pagerLayout="justified"> + <page name="using HTTP/HTTPS" src="setup_transport_http.mkd" /> + <page name="using SSH" src="setup_transport_ssh.mkd" /> + <page name="using the Eclipse plugin" src="eclipse_plugin.mkd" /> </menu> <divider /> <menu name="Tickets" pager="true" pagerPlacement="bottom" pagerLayout="justified"> @@ -877,9 +878,10 @@ <page name="Gitblit as a viewer" src="setup_viewer.mkd" /> </menu> <divider /> - <menu name="Client Configuration" pager="true" pagerPlacement="bottom" pagerLayout="justified"> - <page name="git client setup" src="setup_client.mkd" /> - <page name="eclipse plugin" src="eclipse_plugin.mkd" /> + <menu name="Client Usage" pager="true" pagerPlacement="bottom" pagerLayout="justified"> + <page name="using HTTP/HTTPS" src="setup_transport_http.mkd" /> + <page name="using SSH" src="setup_transport_ssh.mkd" /> + <page name="using the Eclipse plugin" src="eclipse_plugin.mkd" /> </menu> <divider /> <menu name="Tickets" pager="true" pagerPlacement="bottom" pagerLayout="justified"> diff --git a/src/site/setup_client.mkd b/src/site/setup_transport_http.mkd similarity index 88% rename from src/site/setup_client.mkd rename to src/site/setup_transport_http.mkd index d8fc7d1..fd611d4 100644 --- a/src/site/setup_client.mkd +++ b/src/site/setup_transport_http.mkd @@ -1,5 +1,6 @@ -## Client Setup and Configuration +## Using the HTTP/HTTPS transport + ### Https with Self-Signed Certificates You must tell Git/JGit not to verify the self-signed certificate in order to perform any remote Git operations. @@ -42,6 +43,3 @@ fatal: HTTP request failed ``` -### Cloning a Repository - -Gitblit provides many custom clone links for popular Git clients on the Summary page of each repository. If you have one or more of those clients installed, you should be able to click the link to initiate cloning with the selected tool. diff --git a/src/site/setup_transport_ssh.mkd b/src/site/setup_transport_ssh.mkd new file mode 100644 index 0000000..38742ec --- /dev/null +++ b/src/site/setup_transport_ssh.mkd @@ -0,0 +1,87 @@ + +## Using the SSH transport + +*SINCE 1.5.0* + +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. + +### Cloning & Pushing + +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). + +Gitblit will authenticate using username/password or public keys. + + git clone ssh://<username>@<hostname>:29418/myrepository.git + +### Setting up your account to use public key authentication + +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). + +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. + + ssh-keygen + +Then you can upload your *public* key right from the command-line. + + cat ~/.ssh/id_rsa.pub | ssh -l <username> -p 29418 <hostname> gitblit add-key + cat c:\<userfolder>\.ssh\id_rsa.pub | ssh -l <username> -p 29418 <hostname> gitblit add-key + +**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. + +Once you've done both of those steps you should be able to execute the following command without a password prompt. + + ssh -l <username> -p 29418 <hostname> gitblit version + +### Setting up an SSH alias + +Typing the following command syntax all the time gets to be rather tedious. + + ssh -l <username> -p 29418 <hostname> gitblit version + +You can define an alias for your server which will reduce your command syntax to something like this. + + ssh <alias> gitblit version + +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>`. + + Host <alias> + IdentityFile ~/.ssh/id_rsa + User <username> + Port 29418 + HostName <hostname> + +### SSH Commands + +#### git + +You will likely never directly interact with the git command, but it is used by your git client to clone, fetch, and push commits to/from your Gitblit server. + +##### git-receive-pack + +This is the command for processing pushes sent from clients. + +##### git-upload-pack + +This is the command for sending refs and commits to clients. + +#### gitblit + +The *gitblit* command has many subcommands for interacting gitblit. + +##### add-key + +Add an SSH public key to your account. This command accepts a public key piped to stdin. + + cat ~/.ssh/id_rsa.pub | ssh -l <username> -p 29418 <hostname> gitblit add-key + +##### rm-key + +Remove an SSH public key from your account. This command accepts a public key piped to stdin. + + cat ~/.ssh/id_rsa.pub | ssh -l <username> -p 29418 <hostname> gitblit rm-key + +You can also remove all your public keys from your account. + + ssh -l <username> -p 29418 <hostname> gitblit rm-key ALL + + -- Gitblit v1.9.1