increase reflogs lifetime to 7 days
[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@@ifcustom@@, 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@@end@@.</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 @@ifcustom@@
40 <li>Download the <a href="@@path(webadmurl)@@/@@nickname@@_root_cert.pem">root certificate</a>.</li>
41 @@end@@
42 <li>Download your user certificate from the <a href="/reguser.cgi">Register user</a>
43 confirmation page or the <a href="/edituser.cgi">Update user email/SSH Keys</a>
44 page.</li>
45 <li>Identify the file containing your private key.</li>
46 <li>Perform one-time Git global configuration of the @@ifcustom@@root certificate (<tt>http.sslCAInfo</tt>),@@end@@
47 user certificate (<tt>http.sslCert</tt>) and private key (<tt>http.sslKey</tt>) but <em>only</em>
48 for URLs starting with "<tt>@@base(httpspushurl)@@</tt>".</li>
49 </ol>
50 </div>
52 @@ifcustom@@
53 <h3>@@ctr()@@. Download the root certificate</h3>
55 <div class="indent">
56 <p>Download the <a href="@@path(webadmurl)@@/@@nickname@@_root_cert.pem">root certificate</a>
57 (more information about it can be found <a href="@@path(htmlurl)@@/rootcert.html">here</a>).</p>
59 <p>Assuming the root certificate will be stored in "<tt>$HOME/certs</tt>" it may be
60 downloaded like so:</p>
62 <pre class="indent">
63 mkdir -p "$HOME/certs"
64 cd "$HOME/certs"
65 curl -LO "@@server(webadmurl)@@/@@nickname@@_root_cert.pem"
66 </pre>
67 </div>
68 @@end@@
70 <h3>@@ctr()@@. Download your user certificate</h3>
72 <div class="indent">
73 <p>You must register an RSA public key using either the
74 <a href="/reguser.cgi">Register user</a> page or the
75 <a href="/edituser.cgi">Update user email/SSH Keys</a> page.</p>
77 <p>It can then be downloaded from the register user confirmation page
78 or the edit user page.</p>
80 <p>Please note that if you use ssh, you may already have a suitable RSA
81 public key stored in the "<tt>$HOME/.ssh/</tt>" file.</p>
83 <p>If you do not already have a suitable RSA public key (or you want to use
84 a different one for this site) you will need to
85 generate a new RSA key and then register the public key portion using either
86 the <a href="/reguser.cgi">Register user</a> page or the
87 <a href="/edituser.cgi">Update user email/SSH Keys</a> page.</p>
89 <p>A new RSA key (both public and private parts) can be generated using the
90 "<tt>ssh-keygen -t rsa</tt>" command (from OpenSSH) or using a combination of
91 the "<tt>openssl genrsa</tt>" command (from OpenSSL) and the
92 "<tt><a href="">ConvertPubKey</a></tt>"
93 command (from <a href="">EZCert</a>).</p>
95 <p>Download your https push user certificate and store it in the
96 "<tt>$HOME/certs</tt>" directory. The downloaded user certificate file will
97 have a name like "<tt>@@nickname@@_</tt><i>name</i><tt>_user_1.pem</tt>" where
98 "<i>name</i>" is the user name you registered the public key for (the downloaded
99 user certificate file may also have a suffix other than "<tt>_1</tt>" if
100 you&#x2019;ve registered more than one public key).</p>
101 </div>
103 <h3>@@ctr()@@. Locate your private key</h3>
105 <div class="indent">
106 <p>If you registered "<tt>$HOME/.ssh/</tt>" as your public key then
107 your corresponding private key can most likely be found in
108 "<tt>$HOME/.ssh/id_rsa</tt>".</p>
110 <p>If you&#x2019;re using a different RSA public key, you will need the full
111 path to the corresponding private key portion for the next step.</p>
112 </div>
114 <h3>@@ctr()@@. Perform Git global configuration</h3>
116 <div class="indent">
117 <p>Please note that these configuration steps will only be effective for modern Gits
118 (version 1.8.5 or later). If you&#x2019;re dealing with an ancient Git see the
119 <a href="#alternate">alternate instructions</a>.</p>
121 <p>Assuming @@ifcustom@@the root certificate has been downloaded and stored in "<tt>$HOME/certs</tt>",@@end@@
122 the user certificate has been downloaded and stored in "<tt>$HOME/certs</tt>" and
123 the private key is located in "<tt>$HOME/.ssh/id_rsa</tt>", the following will
124 configure Git&#x2019;s @@ifcustom@@"<tt>http.sslCAInfo</tt>", @@end@@"<tt>http.sslCert</tt>" and "<tt>http.sslKey</tt>"
125 settings but <em>only</em> for URLs starting with "<tt>@@base(httpspushurl)@@</tt>":</p>
127 <pre class="indent">
128 @@ifcustom@@git config --global http.@@base(httpspushurl)@@.sslCAInfo \
129 "$HOME/certs/@@nickname@@_root_cert.pem"
131 @@end@@git config --global http.@@base(httpspushurl)@@.sslCert \
132 "$HOME/certs/@@nickname@@_<i>name</i>_user_1.pem"
134 git config --global http.@@base(httpspushurl)@@.sslKey \
135 "$HOME/.ssh/id_rsa"
136 </pre>
138 <p>Your git is now configured and ready to push to this site using
139 an https push URL (presuming your user has push permission to the project
140 you&#x2019;re pushing to). See the <a href="#examples">examples</a> below.</p>
142 <p>If your RSA private key is password protected, you may want to also set
143 the following to avoid overly repetitious entering of the private key&#x2019;s
144 password:</p>
146 <pre class="indent">
147 git config --global http.@@base(httpspushurl)@@.sslCertPasswordProtected true
148 </pre>
150 <p><b>OS X Note</b>: Users of OS X 10.9 and later (including 10.10 etc.) please
151 be advised that the system&#x2019;s cURL library ("<tt>/usr/lib/libcurl.4.dylib</tt>")
152 has <a href=""
153 >problems handling client certificates</a>. If you&#x2019;re using a version of
154 Git that uses that version of the cURL library (Git uses libcurl to talk https),
155 you will be unable to use any downloaded https user push certificate. If you
156 think you might be affected, you can
157 <a href=""
158 >test your Git</a> and if you have a problem, install a
159 <a href="">Git without the problem</a>
160 instead.</p>
161 </div>
163 <h2 id="examples">Examples</h2>
165 <div class="indent">
166 <p>It&#x2019;s possible to both fetch and push over https. It&#x2019;s also
167 possible to fetch over http and push over https. There&#x2019;s an example
168 of each. Both examples assume Git has already been configured as described
169 in the <a href="#instructions">instructions</a>.</p>
171 <pre class="indent">
172 # clone using http
173 git clone @@httppullurl@@/mobexample.git mob1
175 # clone using https
176 git clone @@httpspushurl@@/mobexample.git mob2
178 # configure mob1 to push over https
179 cd /tmp/mob1
180 git remote set-url --push origin @@httpspushurl@@/mobexample.git
181 echo mob1 >> mob1
182 git add mob1
183 git commit -m mob1
184 # push will fail unless your user has push permission
185 git push --all origin
187 # configure mob2 to fetch and push over https
188 cd /tmp/mob2
189 # nothing needs to be done, the clone &amp; global config took care of it
190 echo mob2 >> mob2
191 git add mob2
192 git commit -m mob2
193 # push will fail unless your user has push permission
194 git push --all origin
195 </pre>
196 </div>
198 <h2 id="alternate">Alternative Git Configuration Techniques</h2>
200 <div class="indent">
201 <p>These techniques work with Git version 1.6.6 and later (versions of Git
202 prior to 1.6.6 lack the required smart HTTP protocol support).</p>
204 <pre class="indent">
205 # work in /tmp
206 cd /tmp
208 # clone using http
209 git clone @@httppullurl@@/mobexample.git mob1
211 # clone using https
212 @@ifcustom@@GIT_SSL_CAINFO=$HOME/certs/@@nickname@@_root_cert.pem \
213 @@end@@git clone @@httpspushurl@@/mobexample.git mob2
215 # configure mob1 to push over https
216 cd /tmp/mob1
217 # omitting --global makes these settings repository specific
218 @@ifcustom@@git config http.sslCAInfo $HOME/certs/@@nickname@@_root_cert.pem
219 @@end@@git config http.sslCert $HOME/certs/@@nickname@@_<i>name</i>_user_1.pem
220 git config http.sslKey $HOME/.ssh/id_rsa
221 git remote set-url --push origin @@httpspushurl@@/mobexample.git
222 echo mob1 >> mob1
223 git add mob1
224 git commit -m mob1
225 # push will fail unless your user has push permission
226 git push --all origin
228 # configure mob2 to fetch and push over https
229 cd /tmp/mob2
230 @@ifcustom@@git config http.sslCAInfo $HOME/certs/@@nickname@@_root_cert.pem
231 @@end@@git config http.sslCert $HOME/certs/@@nickname@@_<i>name</i>_user_1.pem
232 git config http.sslKey $HOME/.ssh/id_rsa
233 echo mob2 >> mob2
234 git add mob2
235 git commit -m mob2
236 # push will fail unless your user has push permission
237 git push --all origin
238 </pre>
240 <p>The example <tt>git push</tt> commands above will fail with a push permission
241 error since your user most likely does not have permission to push to the
242 <tt>mobexample.git</tt> project@@ifmob@@, but the mob user can push to the mob branch of
243 <tt>mobexample.git</tt> over https as detailed
244 <a href="@@path(htmlurl)@@/mob.html#httpsmobpush">here</a>@@end@@.</p>
245 </div>
247 <h2>Password Caching</h2>
249 <div class="indent">
250 <p>In the above examples, if the <tt>$HOME/.ssh/id_rsa</tt> private key is password
251 protected, then it&#x2019;s desirable to set <tt>http.sslCertPasswordProtected</tt>
252 to true like so:</p>
254 <pre class="indent">
255 # with the current directory /tmp/mob1 or /tmp/mob2
256 git config --bool http.sslCertPasswordProtected true
257 </pre>
258 </div>