Merge branch 'master' into rorcz
[girocco.git] / 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>