html/httpspush.html

   1 @section=site guide
   2 @heading=How to Setup HTTPS Push
   3 @header
   4
   5 <!-- This file is preprocessed by cgi/html.cgi -->
   6
   7 <p>The https push facility relies on user client authentication certificates to
   8 enable pushing.  These certificates are automatically created whenever an
   9 RSA SSH public key is included in the &#x201c;Public SSH Key(s)&#x201d; section
  10 of the <a href="/reguser.cgi">Register user</a> page and may be downloaded
  11 from the download link(s) shown on the user registration confirmation page
  12 or the <a href="/edituser.cgi">Update user email/SSH Keys</a> page.</p>
  13
  14 <h2>Prerequisites</h2>
  15
  16 <p>Assuming the user login name is <tt>test</tt> and the
  17 <a href="@@path(webadmurl)@@/@@nickname@@_root_cert.pem">root certificate</a>
  18 has been downloaded to <tt>$HOME/certs/@@nickname@@_root_cert.pem</tt> (see
  19 <a href="@@path(htmlurl)@@/rootcert.html">here</a> for more information about the
  20 <a href="@@path(webadmurl)@@/@@nickname@@_root_cert.pem">root certificate</a>),
  21 the single RSA SSH public key from <tt>$HOME/.ssh/id_rsa.pub</tt> has been uploaded
  22 as the sole public key for the <tt>test</tt> user and the resulting
  23 <tt>test</tt> user authentication certifcate has been downloaded to
  24 <tt>$HOME/certs/@@nickname@@_test_user_1.pem</tt>, the following
  25 shows how to clone and then push to a <tt>mobexample.git</tt> project using
  26 only the smart HTTP protocol.</p>
  27
  28 <p style="border:thin dotted black;background-color:#eef;padding:0.5ex 1ex;max-width:90ex">An
  29 https push user authentication certificate may be downloaded from the
  30 <a href="/reguser.cgi">Register user</a> confirmation page or the
  31 <a href="/edituser.cgi">Update user email/SSH Keys</a> page.</p>
  32
  33 <h2>Example</h2>
  34
  35 <p>It&#x2019;s possible to both fetch and push over https.  It&#x2019;s also
  36 possible to fetch over http and push over https.  There&#x2019;s an example
  37 of each.</p>
  38
  39 <pre style="margin:3ex">
  40 # the @@nickname@@ root certificate is in $HOME/certs/@@nickname@@_root_cert.pem
  41 # the test user certificate is in $HOME/certs/@@nickname@@_test_user_1.pem
  42 # the $HOME/.ssh/id_rsa.pub SSH public key was uploaded
  43 # the $HOME/.ssh/id_rsa file is the $HOME/.ssh/id_rsa.pub private key
  44 </pre>
  45
  46 <p id="git185" style="margin:3ex"><b>Using Git version 1.8.5 or later:</b></p>
  47
  48 <pre style="margin:3ex">
  49 # one-time global URL-specific configuration
  50 # (requires Git version 1.8.5 or later)
  51 git config --global http.@@base(httpspushurl)@@.sslCAInfo \
  52                     $HOME/certs/@@nickname@@_root_cert.pem
  53 git config --global http.@@base(httpspushurl)@@.sslCert \
  54                     $HOME/certs/@@nickname@@_test_user_1.pem
  55 git config --global http.@@base(httpspushurl)@@.sslKey \
  56                     $HOME/.ssh/id_rsa
  57
  58 # clone using http
  59 git clone @@httppullurl@@/mobexample.git mob1
  60
  61 # clone using https
  62 git clone @@httpspushurl@@/mobexample.git mob2
  63
  64 # configure mob1 to push over https
  65 cd /tmp/mob1
  66 git remote set-url --push origin @@httpspushurl@@/mobexample.git
  67 echo mob1 >> mob1
  68 git add mob1
  69 git commit -m mob1
  70 # push will fail because test does not have push permission
  71 git push --all origin
  72
  73 # configure mob2 to fetch and push over https
  74 cd /tmp/mob2
  75 # nothing needs to be done, the clone &amp; global config took care of it
  76 echo mob2 >> mob2
  77 git add mob2
  78 git commit -m mob2
  79 # push will fail because test does not have push permission
  80 git push --all origin
  81 </pre>
  82
  83 <p style="margin:3ex"><b>Using any version of Git:</b></p>
  84
  85 <pre style="margin:3ex">
  86 # work in /tmp
  87 cd /tmp
  88
  89 # clone using http
  90 git clone @@httppullurl@@/mobexample.git mob1
  91
  92 # clone using https
  93 GIT_SSL_CAINFO=$HOME/certs/@@nickname@@_root_cert.pem \
  94 git clone @@httpspushurl@@/mobexample.git mob2
  95
  96 # configure mob1 to push over https
  97 cd /tmp/mob1
  98 git config http.sslCAInfo $HOME/certs/@@nickname@@_root_cert.pem
  99 git config http.sslCert $HOME/certs/@@nickname@@_test_user_1.pem
 100 git config http.sslKey $HOME/.ssh/id_rsa
 101 git remote set-url --push origin @@httpspushurl@@/mobexample.git
 102 echo mob1 >> mob1
 103 git add mob1
 104 git commit -m mob1
 105 # push will fail because test does not have push permission
 106 git push --all origin
 107
 108 # configure mob2 to fetch and push over https
 109 cd /tmp/mob2
 110 git config http.sslCAInfo $HOME/certs/@@nickname@@_root_cert.pem
 111 git config http.sslCert $HOME/certs/@@nickname@@_test_user_1.pem
 112 git config http.sslKey $HOME/.ssh/id_rsa
 113 echo mob2 >> mob2
 114 git add mob2
 115 git commit -m mob2
 116 # push will fail because test does not have push permission
 117 git push --all origin
 118 </pre>
 119
 120 <p>The example <tt>git push</tt> commands above will fail with a push permission
 121 error since the test user does not have permission to push to the
 122 <tt>mobexample.git</tt> project@@ifmob@@, but the mob user can push to the mob branch of
 123 <tt>mobexample.git</tt> over https as detailed
 124 <a href="@@path(htmlurl)@@/mob.html#httpsmobpush">here</a>@@end@@.</p>
 125
 126 <h2>Password Caching</h2>
 127
 128 <p>In the above examples, if the <tt>$HOME/.ssh/id_rsa</tt> private key is password
 129 protected, then it&#x2019;s desirable to set <tt>http.sslCertPasswordProtected</tt>
 130 to true like so:</p>
 131
 132 <pre style="margin:3ex">
 133 # with the current directory /tmp/mob1 or /tmp/mob2
 134 git config --bool http.sslCertPasswordProtected true
 135 </pre>
 136
 137 <p>If using Git version 1.8.5 or later the <tt>http.sslCertPasswordProtected</tt> setting
 138 may be applied only to specific URLs (such as <tt>@@base(httpspushurl)@@</tt>).  See the output
 139 of <tt>git config help</tt> for more information.</p>