toolbox/update-all-config.pl: quiet means quiet
[girocco.git] / html / httpspush.html
blob121e8918641e3624d0546324e90a0d10c10ba3d1
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 and make sure it&#x2019;s in a compatible format.</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 &#x201c;<tt>@@base(httpspushurl)@@</tt>&#x201d;.</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 &#x201c;<tt>$HOME/certs</tt>&#x201d; 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>Your user push certificate for that RSA public key can then be
78 downloaded from the register user confirmation page or the edit
79 user page.</p>
81 <p>Please note that if you use ssh, you may already have a suitable RSA
82 public key stored in the &#x201c;<tt>$HOME/.ssh/id_rsa.pub</tt>&#x201d; file.</p>
84 <p>If you do not already have a suitable RSA public key (or you want to use
85 a different one for this site) you will need to
86 generate a new RSA key and then register the public key portion using either
87 the <a href="/reguser.cgi">Register user</a> page or the
88 <a href="/edituser.cgi">Update user email/SSH Keys</a> page.</p>
90 <p>A new RSA key (both public and private parts) can be generated using the
91 &#x201c;<tt>ssh-keygen -t rsa</tt>&#x201d; command (from OpenSSH) or using a combination of
92 the &#x201c;<tt>openssl genrsa</tt>&#x201d; command (from OpenSSL) and the
93 &#x201c;<tt><a href="https://repo.or.cz/ezcert.git/blob/HEAD:/ConvertPubKey#l173">ConvertPubKey</a></tt>&#x201d;
94 command (from <a href="https://repo.or.cz/ezcert.git">EZCert</a>).</p>
96 <p>Download your https push user certificate and store it in the
97 &#x201c;<tt>$HOME/certs</tt>&#x201d; directory. The downloaded user certificate file will
98 have a name like &#x201c;<tt>@@nickname@@_</tt><i>name</i><tt>_user_1.pem</tt>&#x201d; where
99 &#x201c;<i>name</i>&#x201d; is the user name you registered the public key for (the downloaded
100 user certificate file may also have a suffix other than &#x201c;<tt>_1</tt>&#x201d; if
101 you&#x2019;ve registered more than one public key).</p>
102 </div>
104 <h3>@@ctr()@@. Locate your private key and check its format</h3>
106 <div class="indent">
107 <p>If you registered &#x201c;<tt>$HOME/.ssh/id_rsa.pub</tt>&#x201d; as your public key then
108 your corresponding private key can most likely be found in
109 &#x201c;<tt>$HOME/.ssh/id_rsa</tt>&#x201d;.</p>
111 <p>If you&#x2019;re using a different RSA public key, you will need the full
112 path to the corresponding private key portion for the next step.</p>
114 <p>Check the format of your private key. If it&#x2019;s not in the file
115 &#x201c;<tt>$HOME/.ssh/id_rsa</tt>&#x201d;, adjust the following
116 commands accordingly. Run this command:</p>
118 <pre class="indent">
119 head -n 1 "$HOME/.ssh/id_rsa"
120 </pre>
122 <p>If the output is either of these lines:</p>
123 <pre class="indent">-----BEGIN RSA PRIVATE KEY-----
124 -----BEGIN ENCRYPTED PRIVATE KEY-----</pre>
125 <p>Then you&#x2019;re good to go.</p>
127 <p>If the output is &#x201c;<tt>-----BEGIN OPENSSH PRIVATE KEY-----</tt>&#x201d; then you must
128 convert it to one of the other two formats before it can be used for https pushing.</p>
130 <p>If the output of &#x201c;<tt>ssh -V</tt>&#x201d; shows a version of at least 8.1p1 then the recommended
131 format to use is &#x201c;PKCS8&#x201d; (although you may alternatively use the older &#x201c;PEM&#x201d;
132 format if desired) and you can convert your private key file like so:</p>
133 <pre class="indent">ssh-keygen -p -m PKCS8 -f "$HOME/.ssh/id_rsa"</pre>
135 <p>If the output of &#x201c;<tt>ssh -V</tt>&#x201d; shows a version <em>prior</em> to 8.1p1 then you must use the
136 &#x201c;PEM&#x201d; format and you can convert your private key file like so:</p>
137 <pre class="indent">ssh-keygen -p -m PEM -f "$HOME/.ssh/id_rsa"</pre>
139 </div>
141 <h3>@@ctr()@@. Perform Git global configuration</h3>
143 <div class="indent">
144 <p>Please note that these configuration steps will only be effective for modern Gits
145 (version 1.8.5 or later). If you&#x2019;re dealing with an ancient Git see the
146 <a href="#alternate">alternate instructions</a>.</p>
148 <p>Assuming @@ifcustom@@the root certificate has been downloaded and stored in &#x201c;<tt>$HOME/certs</tt>&#x201d;,@@end@@
149 the user certificate has been downloaded and stored in &#x201c;<tt>$HOME/certs</tt>&#x201d; and
150 the private key is located in &#x201c;<tt>$HOME/.ssh/id_rsa</tt>&#x201d;, the following will
151 configure Git&#x2019;s @@ifcustom@@&#x201c;<tt>http.sslCAInfo</tt>&#x201d;, @@end@@&#x201c;<tt>http.sslCert</tt>&#x201d; and &#x201c;<tt>http.sslKey</tt>&#x201d;
152 settings but <em>only</em> for URLs starting with &#x201c;<tt>@@base(httpspushurl)@@</tt>&#x201d;:</p>
154 <pre class="indent">
155 @@ifcustom@@git config --global http.@@base(httpspushurl)@@.sslCAInfo \
156 "$HOME/certs/@@nickname@@_root_cert.pem"
158 @@end@@git config --global http.@@base(httpspushurl)@@.sslCert \
159 "$HOME/certs/@@nickname@@_<i>name</i>_user_1.pem"
161 git config --global http.@@base(httpspushurl)@@.sslKey \
162 "$HOME/.ssh/id_rsa"
163 </pre>
165 <p>Your git is now configured and ready to push to this site using
166 an https push URL (presuming your user has push permission to the project
167 you&#x2019;re pushing to). See the <a href="#examples">examples</a> below.</p>
169 <p>If your RSA private key is password protected, you may want to also set
170 the following to avoid overly repetitious entering of the private key&#x2019;s
171 password:</p>
173 <pre class="indent">
174 git config --global http.@@base(httpspushurl)@@.sslCertPasswordProtected true
175 </pre>
177 <p><b>OS X Note</b>: Users of OS X 10.9 and later (including 10.10 etc.) please
178 be advised that the system&#x2019;s curl library (&#x201c;<tt>/usr/lib/libcurl.4.dylib</tt>&#x201d;)
179 has <a href="https://mackyle.github.io/git-osx-installer/iscurlsick.html#problem"
180 >problems handling client certificates</a>. If you&#x2019;re using a version of
181 Git that uses that version of the curl library (Git uses libcurl to talk https),
182 you will be unable to use any downloaded https user push certificate. If you
183 think you might be affected, you can
184 <a href="https://mackyle.github.io/git-osx-installer/iscurlsick.html#gittest"
185 >test your Git</a> and if you have a problem, install a
186 <a href="https://mackyle.github.io/git-osx-installer/">Git without the problem</a>
187 instead. (Reportedly this issue MAY have been addressed starting with Mac OS X 10.13,
188 but it doesn't hurt to <a href="https://mackyle.github.io/git-osx-installer/iscurlsick.html#gittest"
189 >test your Git</a> just to be sure.)</p>
190 </div>
192 <h2 id="examples">Examples</h2>
194 <div class="indent">
195 <p>It&#x2019;s possible to both fetch and push over https. It&#x2019;s also
196 possible to fetch over http and push over https. There&#x2019;s an example
197 of each. Both examples assume Git has already been configured as described
198 in the <a href="#instructions">instructions</a>.</p>
200 <pre class="indent">
201 # clone using http
202 git clone @@httppullurl@@/mobexample.git mob1
204 # clone using https
205 git clone @@httpspushurl@@/mobexample.git mob2
207 # configure mob1 to push over https
208 cd /tmp/mob1
209 git remote set-url --push origin @@httpspushurl@@/mobexample.git
210 echo mob1 >> mob1
211 git add mob1
212 git commit -m mob1
213 # push will fail unless your user has push permission
214 git push --all origin
216 # configure mob2 to fetch and push over https
217 cd /tmp/mob2
218 # nothing needs to be done, the clone &amp; global config took care of it
219 echo mob2 >> mob2
220 git add mob2
221 git commit -m mob2
222 # push will fail unless your user has push permission
223 git push --all origin
224 </pre>
225 </div>
227 <h2 id="alternate">Alternative Git Configuration Techniques</h2>
229 <div class="indent">
230 <p>These techniques work with Git version 1.6.6 and later (versions of Git
231 prior to 1.6.6 lack the required smart HTTP protocol support).</p>
233 <pre class="indent">
234 # work in /tmp
235 cd /tmp
237 # clone using http
238 git clone @@httppullurl@@/mobexample.git mob1
240 # clone using https
241 @@ifcustom@@GIT_SSL_CAINFO=$HOME/certs/@@nickname@@_root_cert.pem \
242 @@end@@git clone @@httpspushurl@@/mobexample.git mob2
244 # configure mob1 to push over https
245 cd /tmp/mob1
246 # omitting --global makes these settings repository specific
247 @@ifcustom@@git config http.sslCAInfo $HOME/certs/@@nickname@@_root_cert.pem
248 @@end@@git config http.sslCert $HOME/certs/@@nickname@@_<i>name</i>_user_1.pem
249 git config http.sslKey $HOME/.ssh/id_rsa
250 git remote set-url --push origin @@httpspushurl@@/mobexample.git
251 echo mob1 >> mob1
252 git add mob1
253 git commit -m mob1
254 # push will fail unless your user has push permission
255 git push --all origin
257 # configure mob2 to fetch and push over https
258 cd /tmp/mob2
259 @@ifcustom@@git config http.sslCAInfo $HOME/certs/@@nickname@@_root_cert.pem
260 @@end@@git config http.sslCert $HOME/certs/@@nickname@@_<i>name</i>_user_1.pem
261 git config http.sslKey $HOME/.ssh/id_rsa
262 echo mob2 >> mob2
263 git add mob2
264 git commit -m mob2
265 # push will fail unless your user has push permission
266 git push --all origin
267 </pre>
269 <p>The example <tt>git push</tt> commands above will fail with a push permission
270 error since your user most likely does not have permission to push to the
271 <tt>mobexample.git</tt> project@@ifmob@@, but the mob user can push to the mob branch of
272 <tt>mobexample.git</tt> over https as detailed
273 <a href="@@path(htmlurl)@@/mob.html#httpsmobpush">here</a>@@end@@.</p>
274 </div>
276 <h2>Password Caching</h2>
278 <div class="indent">
279 <p>In the above examples, if the &#x201c;<tt>$HOME/.ssh/id_rsa</tt>&#x201d; private key is password
280 protected, then it&#x2019;s desirable to set <tt>http.sslCertPasswordProtected</tt>
281 to true like so:</p>
283 <pre class="indent">
284 # with the current directory /tmp/mob1 or /tmp/mob2
285 git config --bool http.sslCertPasswordProtected true
286 </pre>
287 </div>