Merge branch 'master' into rorcz
[girocco.git] / html / httpspush.html
1 @section=site guide
2 @heading=How to Setup HTTPS Push
3 @header
5 <!-- This file is preprocessed by cgi/html.cgi -->
7 <h2>Overview</h2>
9 <div class="indent">
10 <p>The https push facility relies on user client authentication certificates to
11 enable pushing. These certificates are automatically created whenever an
12 RSA SSH public key is included in the &#x201c;Public SSH Key(s)&#x201d; section
13 of the <a href="/reguser.cgi">Register user</a> page and may be downloaded
14 from the download link(s) shown on the user registration confirmation page
15 or the <a href="/edituser.cgi">Update user email/SSH Keys</a> page.</p>
17 <p>A user client certificate is <em>NOT</em> required to fetch using https, but you will
18 likely need to configure the root certificate (if you haven&#x2019;t already done so). See
19 <a href="rootcert.html#quick">the instructions to quickly and easily configure the root certificate</a>
20 if you only want to fetch over https and don&#x2019;t currently need to push.</p>
22 <p style="border:thin dotted black;background-color:#eef;padding:0.5ex 1ex;max-width:90ex">An
23 https push user authentication certificate may be downloaded from the
24 <a href="/reguser.cgi">Register user</a> confirmation page or the
25 <a href="/edituser.cgi">Update user email/SSH Keys</a> page.</p>
26 </div>
28 <h2 id="instructions">Instructions</h2>
30 <div class="indent">
31 <p><b>Note</b>: These instructions are for modern Gits. If you have
32 an ancient Git (i.e. prior to version 1.8.5) see the
33 <a href="#alternate">alternate instructions</a> below.</p>
34 </div>
36 <h3>0. Quick Overview</h3>
37 <div>
38 <ol>
39 <li>Download the <a href="@@path(webadmurl)@@/@@nickname@@_root_cert.pem">root certificate</a>.</li>
40 <li>Download your user certificate from the <a href="/reguser.cgi">Register user</a>
41 confirmation page or the <a href="/edituser.cgi">Update user email/SSH Keys</a>
42 page.</li>
43 <li>Identify the file containing your private key.</li>
44 <li>Perform one-time Git global configuration of the root certificate (<tt>http.sslCAInfo</tt>),
45 user certificate (<tt>http.sslCert</tt>) and private key (<tt>http.sslKey</tt>) but <em>only</em>
46 for URLs starting with "<tt>@@base(httpspushurl)@@</tt>".</li>
47 </ol>
48 </div>
50 <h3>1. Download the root certificate</h3>
52 <div class="indent">
53 <p>Download the <a href="@@path(webadmurl)@@/@@nickname@@_root_cert.pem">root certificate</a>
54 (more information about it can be found <a href="@@path(htmlurl)@@/rootcert.html">here</a>).</p>
56 <p>Assuming the root certificate will be stored in "<tt>$HOME/certs</tt>" it may be
57 downloaded like so:</p>
59 <pre class="indent">
60 mkdir -p "$HOME/certs"
61 cd "$HOME/certs"
62 curl -LO "@@server(webadmurl)@@/@@nickname@@_root_cert.pem"
63 </pre>
64 </div>
66 <h3>2. Download your user certificate</h3>
68 <div class="indent">
69 <p>You must register an RSA public key using either the
70 <a href="/reguser.cgi">Register user</a> page or the
71 <a href="/edituser.cgi">Update user email/SSH Keys</a> page.</p>
73 <p>It can then be downloaded from the register user confirmation page
74 or the edit user page.</p>
76 <p>Please note that if you use ssh, you may already have a suitable RSA
77 public key stored in the "<tt>$HOME/.ssh/</tt>" file.</p>
79 <p>If you do not already have a suitable RSA public key (or you want to use
80 a different one for this site) you will need to
81 generate a new RSA key and then register the public key portion using either
82 the <a href="/reguser.cgi">Register user</a> page or the
83 <a href="/edituser.cgi">Update user email/SSH Keys</a> page.</p>
85 <p>A new RSA key (both public and private parts) can be generated using the
86 "<tt>ssh-keygen -t rsa</tt>" command (from OpenSSH) or using a combination of
87 the "<tt>openssl genrsa</tt>" command (from OpenSSL) and the
88 "<tt><a href="">ConvertPubKey</a></tt>"
89 command (from <a href="">EZCert</a>).</p>
91 <p>Download your https push user certificate and store it in the
92 "<tt>$HOME/certs</tt>" directory. The downloaded user certificate file will
93 have a name like "<tt>@@nickname@@_</tt><i>name</i><tt>_user_1.pem</tt>" where
94 "<i>name</i>" is the user name you registered the public key for (the downloaded
95 user certificate file may also have a suffix other than "<tt>_1</tt>" if
96 you&#x2019;ve registered more than one public key).</p>
97 </div>
99 <h3>3. Locate your private key</h3>
101 <div class="indent">
102 <p>If you registered "<tt>$HOME/.ssh/</tt>" as your public key then
103 your corresponding private key can most likely be found in
104 "<tt>$HOME/.ssh/id_rsa</tt>".</p>
106 <p>If you&#x2019;re using a different RSA public key, you will need the full
107 path to the corresponding private key portion for the next step.</p>
108 </div>
110 <h3>4. Perform Git global configuration</h3>
112 <div class="indent">
113 <p>Please note that these configuration steps will only be effective for modern Gits
114 (version 1.8.5 or later). If you&#x2019;re dealing with an ancient Git see the
115 <a href="#alternate">alternate instructions</a>.</p>
117 <p>Assuming the root certificate and user certificate have been downloaded and
118 stored in "<tt>$HOME/certs</tt>" and the private key is located in
119 "<tt>$HOME/.ssh/id_rsa</tt>", the following will configure Git&#x2019;s
120 "<tt>http.sslCAInfo</tt>", "<tt>http.sslCert</tt>" and "<tt>http.sslKey</tt>"
121 settings but <em>only</em> for URLs starting with "<tt>@@base(httpspushurl)@@</tt>":</p>
123 <pre class="indent">
124 git config --global http.@@base(httpspushurl)@@.sslCAInfo \
125 "$HOME/certs/@@nickname@@_root_cert.pem"
127 git config --global http.@@base(httpspushurl)@@.sslCert \
128 "$HOME/certs/@@nickname@@_<i>name</i>_user_1.pem
130 git config --global http.@@base(httpspushurl)@@.sslKey \
131 "$HOME/.ssh/id_rsa"
132 </pre>
134 <p>Your git is now configured and ready to push to this site using
135 an https push URL (presuming your user has push permission to the project
136 you&#x2019;re pushing to). See the <a href="#examples">examples</a> below.</p>
138 <p>If your RSA private key is password protected, you may want to also set
139 the following to avoid overly repetitious entering of the private key&#x2019;s
140 password:</p>
142 <pre class="indent">
143 git config --global http.@@base(httpspushurl)@@.sslCertPasswordProtected true
144 </pre>
146 <p><b>OS X Note</b>: Users of OS X 10.9 and later (including 10.10 etc.) please
147 be advised that the system&#x2019;s cURL library ("<tt>/usr/lib/libcurl.4.dylib</tt>")
148 has <a href=""
149 >problems handling client certificates</a>. If you&#x2019;re using a version of
150 Git that uses that version of the cURL library (Git uses libcurl to talk https),
151 you will be unable to use any downloaded https user push certificate. If you
152 think you might be affected, you can
153 <a href=""
154 >test your Git</a> and if you have a problem, install a
155 <a href="">Git without the problem</a>
156 instead.</p>
157 </div>
159 <h2 id="examples">Examples</h2>
161 <div class="indent">
162 <p>It&#x2019;s possible to both fetch and push over https. It&#x2019;s also
163 possible to fetch over http and push over https. There&#x2019;s an example
164 of each. Both examples assume Git has already been configured as described
165 in the <a href="#instructions">instructions</a>.</p>
167 <pre class="indent">
168 # clone using http
169 git clone @@httppullurl@@/mobexample.git mob1
171 # clone using https
172 git clone @@httpspushurl@@/mobexample.git mob2
174 # configure mob1 to push over https
175 cd /tmp/mob1
176 git remote set-url --push origin @@httpspushurl@@/mobexample.git
177 echo mob1 >> mob1
178 git add mob1
179 git commit -m mob1
180 # push will fail unless your user has push permission
181 git push --all origin
183 # configure mob2 to fetch and push over https
184 cd /tmp/mob2
185 # nothing needs to be done, the clone &amp; global config took care of it
186 echo mob2 >> mob2
187 git add mob2
188 git commit -m mob2
189 # push will fail unless your user has push permission
190 git push --all origin
191 </pre>
192 </div>
194 <h2 id="alternate">Alternative Git Configuration Techniques</h2>
196 <div class="indent">
197 <p>These techniques work with Git version 1.6.6 and later (versions of Git
198 prior to 1.6.6 lack the required smart HTTP protocol support).</p>
200 <pre class="indent">
201 # work in /tmp
202 cd /tmp
204 # clone using http
205 git clone @@httppullurl@@/mobexample.git mob1
207 # clone using https
208 GIT_SSL_CAINFO=$HOME/certs/@@nickname@@_root_cert.pem \
209 git clone @@httpspushurl@@/mobexample.git mob2
211 # configure mob1 to push over https
212 cd /tmp/mob1
213 # omitting --global makes these settings repository specific
214 git config http.sslCAInfo $HOME/certs/@@nickname@@_root_cert.pem
215 git config http.sslCert $HOME/certs/@@nickname@@_<i>name</i>_user_1.pem
216 git config http.sslKey $HOME/.ssh/id_rsa
217 git remote set-url --push origin @@httpspushurl@@/mobexample.git
218 echo mob1 >> mob1
219 git add mob1
220 git commit -m mob1
221 # push will fail unless your user has push permission
222 git push --all origin
224 # configure mob2 to fetch and push over https
225 cd /tmp/mob2
226 git config http.sslCAInfo $HOME/certs/@@nickname@@_root_cert.pem
227 git config http.sslCert $HOME/certs/@@nickname@@_<i>name</i>_user_1.pem
228 git config http.sslKey $HOME/.ssh/id_rsa
229 echo mob2 >> mob2
230 git add mob2
231 git commit -m mob2
232 # push will fail unless your user has push permission
233 git push --all origin
234 </pre>
236 <p>The example <tt>git push</tt> commands above will fail with a push permission
237 error since your user most likely does not have permission to push to the
238 <tt>mobexample.git</tt> project@@ifmob@@, but the mob user can push to the mob branch of
239 <tt>mobexample.git</tt> over https as detailed
240 <a href="@@path(htmlurl)@@/mob.html#httpsmobpush">here</a>@@end@@.</p>
241 </div>
243 <h2>Password Caching</h2>
245 <div class="indent">
246 <p>In the above examples, if the <tt>$HOME/.ssh/id_rsa</tt> private key is password
247 protected, then it&#x2019;s desirable to set <tt>http.sslCertPasswordProtected</tt>
248 to true like so:</p>
250 <pre class="indent">
251 # with the current directory /tmp/mob1 or /tmp/mob2
252 git config --bool http.sslCertPasswordProtected true
253 </pre>
254 </div>