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 style="border:thin dotted black;background-color:#eef;padding:0.5ex 1ex;max-width:90ex">An
18 https push user authentication certificate may be downloaded from the
19 <a href="/reguser.cgi">Register user</a> confirmation page or the
20 <a href="/edituser.cgi">Update user email/SSH Keys</a> page.</p>
21 </div>
23 <h2 id="instructions">Instructions</h2>
25 <div class="indent">
26 <p><b>Note</b>: These instructions are for modern Gits. If you have
27 an ancient Git (i.e. prior to version 1.8.5) see the
28 <a href="#alternate">alternate instructions</a> below.</p>
29 </div>
31 <h3>0. Quick Overview</h3>
32 <div>
33 <ol>
34 <li>Download the <a href="@@path(webadmurl)@@/@@nickname@@_root_cert.pem">root certificate</a>.</li>
35 <li>Download your user certificate from the <a href="/reguser.cgi">Register user</a>
36 confirmation page or the <a href="/edituser.cgi">Update user email/SSH Keys</a>
37 page.</li>
38 <li>Identify the file containing your private key.</li>
39 <li>Perform one-time Git global configuration of the root certificate (<tt>http.sslCAInfo</tt>),
40 user certificate (<tt>http.sslCert</tt>) and private key (<tt>http.sslKey</tt>) but <em>only</em>
41 for URLs starting with "<tt>@@base(httpspushurl)@@</tt>".</li>
42 </ol>
43 </div>
45 <h3>1. Download the root certificate</h3>
47 <div class="indent">
48 <p>Download the <a href="@@path(webadmurl)@@/@@nickname@@_root_cert.pem">root certificate</a>
49 (more information about it can be found <a href="@@path(htmlurl)@@/rootcert.html">here</a>).</p>
51 <p>Assuming the root certificate will be stored in "<tt>$HOME/certs</tt>" it may be
52 downloaded like so:</p>
54 <pre class="indent">
55 mkdir -p "$HOME/certs"
56 cd "$HOME/certs"
57 curl -LO "@@server(webadmurl)@@/@@nickname@@_root_cert.pem"
58 </pre>
59 </div>
61 <h3>2. Download your user certificate</h3>
63 <div class="indent">
64 <p>You must register an RSA public key using either the
65 <a href="/reguser.cgi">Register user</a> page or the
66 <a href="/edituser.cgi">Update user email/SSH Keys</a> page.</p>
68 <p>It can then be downloaded from the register user confirmation page
69 or the edit user page.</p>
71 <p>Please note that if you use ssh, you may already have a suitable RSA
72 public key stored in the "<tt>$HOME/.ssh/</tt>" file.</p>
74 <p>If you do not already have a suitable RSA public key (or you want to use
75 a different one for this site) you will need to
76 generate a new RSA key and then register the public key portion using either
77 the <a href="/reguser.cgi">Register user</a> page or the
78 <a href="/edituser.cgi">Update user email/SSH Keys</a> page.</p>
80 <p>A new RSA key (both public and private parts) can be generated using the
81 "<tt>ssh-keygen -t rsa</tt>" command (from OpenSSH) or using a combination of
82 the "<tt>openssl genrsa</tt>" command (from OpenSSL) and the
83 "<tt><a href="">ConvertPubKey</a></tt>"
84 command (from <a href="">EZCert</a>).</p>
86 <p>Download your https push user certificate and store it in the
87 "<tt>$HOME/certs</tt>" directory. The downloaded user certificate file will
88 have a name like "<tt>@@nickname@@_</tt><i>name</i><tt>_user_1.pem</tt>" where
89 "<i>name</i>" is the user name you registered the public key for (it may
90 also have a suffix other than "<tt>_1</tt>" if you&#x2019;ve registered more
91 than one public key).</p>
92 </div>
94 <h3>3. Locate your private key</h3>
96 <div class="indent">
97 <p>If you registered "<tt>$HOME/.ssh/</tt>" as your public key then
98 your corresponding private key can most likely be found in
99 "<tt>$HOME/.ssh/id_rsa</tt>".</p>
101 <p>If you&#x2019;re using a different RSA public key, you will need the full
102 path to the corresponding private key portion for the next step.</p>
103 </div>
105 <h3>4. Perform Git global configuration</h3>
107 <div class="indent">
108 <p>Please note that these configuration steps will only be effective for modern Gits
109 (version 1.8.5 or later). If you&#x2019;re dealing with an ancient Git see the
110 <a href="#alternate">alternate instructions</a>.</p>
112 <p>Assuming the root certificate and user certificate have been downloaded and
113 stored in "<tt>$HOME/certs</tt>" and the private key is located in
114 "<tt>$HOME/.ssh/id_rsa</tt>", the following will configure Git&#x2019;s
115 "<tt>http.sslCAInfo</tt>", "<tt>http.sslCert</tt>" and "<tt>http.sslKey</tt>"
116 settings but <em>only</em> for URLs starting with "<tt>@@base(httpspushurl)@@</tt>":</p>
118 <pre class="indent">
119 git config --global http.@@base(httpspushurl)@@.sslCAInfo \
120 "$HOME/certs/@@nickname@@_root_cert.pem"
122 git config --global http.@@base(httpspushurl)@@.sslCert \
123 "$HOME/certs/@@nickname@@_<i>name</i>_user_1.pem
125 git config --global http.@@base(httpspushurl)@@.sslKey \
126 "$HOME/.ssh/id_rsa"
127 </pre>
129 <p>Your git is now configured and ready to push to this site using
130 an https push URL (presuming your user has push permission to the project
131 you&#x2019;re pushing to). See the <a href="#examples">examples</a> below.</p>
133 <p>If your RSA private key is password protected, you may want to also set
134 the following to avoid overly repetitious entering of the private key&#x2019;s
135 password:</p>
137 <pre class="indent">
138 git config --global http.@@base(httpspushurl)@@.sslCertPasswordProtected true
139 </pre>
141 <p><b>OS X Note</b>: Users of OS X 10.9 and later (including 10.10 etc.) please
142 be advised that the system&#x2019;s cURL library ("<tt>/usr/lib/libcurl.4.dylib</tt>")
143 has <a href=""
144 >problems handling client certificates</a>. If you&#x2019;re using a version of
145 Git that uses that version of the cURL library (Git uses libcurl to talk https),
146 you will be unable to use any downloaded https user push certificate. If you
147 think you might be affected, you can
148 <a href=""
149 >test your Git</a> and if you have a problem, install a
150 <a href="">Git without the problem</a>
151 instead.</p>
152 </div>
154 <h2 id="examples">Examples</h2>
156 <div class="indent">
157 <p>It&#x2019;s possible to both fetch and push over https. It&#x2019;s also
158 possible to fetch over http and push over https. There&#x2019;s an example
159 of each. Both examples assume Git has already been configured as described
160 in the <a href="#instructions">instructions</a>.</p>
162 <pre class="indent">
163 # clone using http
164 git clone @@httppullurl@@/mobexample.git mob1
166 # clone using https
167 git clone @@httpspushurl@@/mobexample.git mob2
169 # configure mob1 to push over https
170 cd /tmp/mob1
171 git remote set-url --push origin @@httpspushurl@@/mobexample.git
172 echo mob1 >> mob1
173 git add mob1
174 git commit -m mob1
175 # push will fail unless your user has push permission
176 git push --all origin
178 # configure mob2 to fetch and push over https
179 cd /tmp/mob2
180 # nothing needs to be done, the clone &amp; global config took care of it
181 echo mob2 >> mob2
182 git add mob2
183 git commit -m mob2
184 # push will fail unless your user has push permission
185 git push --all origin
186 </pre>
187 </div>
189 <h2 id="alternate">Alternative Git Configuration Techniques</h2>
191 <div class="indent">
192 <p>These techniques work with Git version 1.6.6 and later (versions of Git
193 prior to 1.6.6 lack the required smart HTTP protocol support).</p>
195 <pre class="indent">
196 # work in /tmp
197 cd /tmp
199 # clone using http
200 git clone @@httppullurl@@/mobexample.git mob1
202 # clone using https
203 GIT_SSL_CAINFO=$HOME/certs/@@nickname@@_root_cert.pem \
204 git clone @@httpspushurl@@/mobexample.git mob2
206 # configure mob1 to push over https
207 cd /tmp/mob1
208 # omitting --global makes these settings repository specific
209 git config http.sslCAInfo $HOME/certs/@@nickname@@_root_cert.pem
210 git config http.sslCert $HOME/certs/@@nickname@@_<i>name</i>_user_1.pem
211 git config http.sslKey $HOME/.ssh/id_rsa
212 git remote set-url --push origin @@httpspushurl@@/mobexample.git
213 echo mob1 >> mob1
214 git add mob1
215 git commit -m mob1
216 # push will fail unless your user has push permission
217 git push --all origin
219 # configure mob2 to fetch and push over https
220 cd /tmp/mob2
221 git config http.sslCAInfo $HOME/certs/@@nickname@@_root_cert.pem
222 git config http.sslCert $HOME/certs/@@nickname@@_<i>name</i>_user_1.pem
223 git config http.sslKey $HOME/.ssh/id_rsa
224 echo mob2 >> mob2
225 git add mob2
226 git commit -m mob2
227 # push will fail unless your user has push permission
228 git push --all origin
229 </pre>
231 <p>The example <tt>git push</tt> commands above will fail with a push permission
232 error since your user most likely does not have permission to push to the
233 <tt>mobexample.git</tt> project@@ifmob@@, but the mob user can push to the mob branch of
234 <tt>mobexample.git</tt> over https as detailed
235 <a href="@@path(htmlurl)@@/mob.html#httpsmobpush">here</a>@@end@@.</p>
236 </div>
238 <h2>Password Caching</h2>
240 <div class="indent">
241 <p>In the above examples, if the <tt>$HOME/.ssh/id_rsa</tt> private key is password
242 protected, then it&#x2019;s desirable to set <tt>http.sslCertPasswordProtected</tt>
243 to true like so:</p>
245 <pre class="indent">
246 # with the current directory /tmp/mob1 or /tmp/mob2
247 git config --bool http.sslCertPasswordProtected true
248 </pre>
249 </div>