hgbook
changeset 210:27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Wed Apr 25 15:23:44 2007 -0700 (2007-04-25) |
parents | 8b599dcca584 |
children | b461d7ead9e1 |
files | en/collab.tex |
line diff
1.1 --- a/en/collab.tex Wed Apr 25 13:06:30 2007 -0700 1.2 +++ b/en/collab.tex Wed Apr 25 15:23:44 2007 -0700 1.3 @@ -328,7 +328,10 @@ 1.4 1.5 \section{The technical side of sharing} 1.6 1.7 -\subsection{Informal sharing with \hgcmd{serve}} 1.8 +The remainder of this chapter is devoted to the question of serving 1.9 +data to your collaborators. 1.10 + 1.11 +\section{Informal sharing with \hgcmd{serve}} 1.12 \label{sec:collab:serve} 1.13 1.14 Mercurial's \hgcmd{serve} command is wonderfully suited to small, 1.15 @@ -362,7 +365,7 @@ 1.16 This can help you to quickly get acquainted with using commands on 1.17 network-hosted repositories. 1.18 1.19 -\subsubsection{A few things to keep in mind} 1.20 +\subsection{A few things to keep in mind} 1.21 1.22 Because it provides unauthenticated read access to all clients, you 1.23 should only use \hgcmd{serve} in an environment where you either don't 1.24 @@ -386,7 +389,7 @@ 1.25 correctly, and find out what URL you should send to your 1.26 collaborators, start it with the \hggopt{-v} option. 1.27 1.28 -\subsection{Using the Secure Shell (ssh) protocol} 1.29 +\section{Using the Secure Shell (ssh) protocol} 1.30 \label{sec:collab:ssh} 1.31 1.32 You can pull and push changes securely over a network connection using 1.33 @@ -402,7 +405,7 @@ 1.34 (If you \emph{are} familiar with ssh, you'll probably find some of the 1.35 material that follows to be elementary in nature.) 1.36 1.37 -\subsubsection{How to read and write ssh URLs} 1.38 +\subsection{How to read and write ssh URLs} 1.39 1.40 An ssh URL tends to look like this: 1.41 \begin{codesample2} 1.42 @@ -449,7 +452,7 @@ 1.43 ssh://server//absolute/path 1.44 \end{codesample2} 1.45 1.46 -\subsubsection{Finding an ssh client for your system} 1.47 +\subsection{Finding an ssh client for your system} 1.48 1.49 Almost every Unix-like system comes with OpenSSH preinstalled. If 1.50 you're using such a system, run \Verb|which ssh| to find out if 1.51 @@ -482,7 +485,7 @@ 1.52 idea). 1.53 \end{note} 1.54 1.55 -\subsubsection{Generating a key pair} 1.56 +\subsection{Generating a key pair} 1.57 1.58 To avoid the need to repetitively type a password every time you need 1.59 to use your ssh client, I recommend generating a key pair. On a 1.60 @@ -508,7 +511,7 @@ 1.61 window it's displayed in straight into the 1.62 \sfilename{authorized\_keys} file. 1.63 1.64 -\subsubsection{Using an authentication agent} 1.65 +\subsection{Using an authentication agent} 1.66 1.67 An authentication agent is a daemon that stores passphrases in memory 1.68 (so it will forget passphrases if you log out and log back in again). 1.69 @@ -531,7 +534,7 @@ 1.70 command acts as the agent. It adds an icon to your system tray that 1.71 will let you manage stored passphrases. 1.72 1.73 -\subsubsection{Configuring the server side properly} 1.74 +\subsection{Configuring the server side properly} 1.75 1.76 Because ssh can be fiddly to set up if you're new to it, there's a 1.77 variety of things that can go wrong. Add Mercurial on top, and 1.78 @@ -648,7 +651,7 @@ 1.79 point, try using the \hggopt{--debug} option to get a clearer picture 1.80 of what's going on. 1.81 1.82 -\subsubsection{Using compression with ssh} 1.83 +\subsection{Using compression with ssh} 1.84 1.85 Mercurial does not compress data when it uses the ssh protocol, 1.86 because the ssh protocol can transparently compress data. However, 1.87 @@ -683,9 +686,185 @@ 1.88 and use compression. This gives you both a shorter name to type and 1.89 compression, each of which is a good thing in its own right. 1.90 1.91 -\subsection{Serving over HTTP with a CGI script} 1.92 +\section{Serving over HTTP using CGI} 1.93 \label{sec:collab:cgi} 1.94 1.95 +Depending on how ambitious you are, configuring Mercurial's CGI 1.96 +interface can take anything from a few moments to several hours. 1.97 + 1.98 +We'll begin with the simplest of examples, and work our way towards a 1.99 +more complex configuration. Even for the most basic case, you're 1.100 +almost certainly going to need to read and modify your web server's 1.101 +configuration. 1.102 + 1.103 +\begin{note} 1.104 + Configuring a web server is a complex, fiddly, and highly 1.105 + system-dependent activity. I can't possibly give you instructions 1.106 + that will cover anything like all of the cases you will encounter. 1.107 + Please use your discretion and judgment in following the sections 1.108 + below. Be prepared to make plenty of mistakes, and to spend a lot 1.109 + of time reading your server's error logs. 1.110 +\end{note} 1.111 + 1.112 +\subsection{Web server configuration checklist} 1.113 + 1.114 +Before you continue, do take a few moments to check a few aspects of 1.115 +your system's setup. 1.116 + 1.117 +\begin{enumerate} 1.118 +\item Do you have a web server installed at all? Mac OS X ships with 1.119 + Apache, but many other systems may not have a web server installed. 1.120 +\item If you have a web server installed, is it actually running? On 1.121 + most systems, even if one is present, it will be disabled by 1.122 + default. 1.123 +\item Is your server configured to allow you to run CGI programs in 1.124 + the directory where you plan to do so? Most servers default to 1.125 + explicitly disabling the ability to run CGI programs. 1.126 +\end{enumerate} 1.127 + 1.128 +If you don't have a web server installed, and don't have substantial 1.129 +experience configuring Apache, you should consider using the 1.130 +\texttt{lighttpd} web server instead of Apache. Apache has a 1.131 +well-deserved reputation for baroque and confusing configuration. 1.132 +While \texttt{lighttpd} is less capable in some ways than Apache, most 1.133 +of these capabilities are not relevant to serving Mercurial 1.134 +repositories. And \texttt{lighttpd} is undeniably \emph{much} easier 1.135 +to get started with than Apache. 1.136 + 1.137 +\subsection{Basic CGI configuration} 1.138 + 1.139 +On Unix-like systems, it's common for users to have a subdirectory 1.140 +named something like \dirname{public\_html} in their home directory, 1.141 +from which they can serve up web pages. A file named \filename{foo} 1.142 +in this directory will be accessible at a URL of the form 1.143 +\texttt{http://www.example.com/\~username/foo}. 1.144 + 1.145 +To get started, find the \sfilename{hgweb.cgi} script that should be 1.146 +present in your Mercurial installation. If you can't quickly find a 1.147 +local copy on your system, simply download one from the master 1.148 +Mercurial repository at 1.149 +\url{http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi}. 1.150 + 1.151 +You'll need to copy this script into your \dirname{public\_html} 1.152 +directory, and ensure that it's executable. 1.153 +\begin{codesample2} 1.154 + cp .../hgweb.cgi ~/public_html 1.155 + chmod +x ~/public_html/hgweb.cgi 1.156 +\end{codesample2} 1.157 + 1.158 +\subsubsection{What could \emph{possibly} go wrong?} 1.159 + 1.160 +Once you've copied the CGI script into place, go into a web browser, 1.161 +and try to open the URL \url{http://myhostname/~myuser/hgweb.cgi}, 1.162 +\emph{but} brace yourself for instant failure. There's a high 1.163 +probability that trying to visit this URL will fail, and there are 1.164 +many possible reasons for this. In fact, you're likely to stumble 1.165 +over almost every one of the possible errors below, so please read 1.166 +carefully. The following are all of the problems I ran into on a 1.167 +system running Fedora~7, with a fresh installation of Apache, and a 1.168 +user account that I created specially. 1.169 + 1.170 +Your web server may have per-user directories disabled. If you're 1.171 +using Apache, search your config file for a \texttt{UserDir} 1.172 +directive. If there's none present, per-user directories will be 1.173 +disabled. If one exists, but its value is \texttt{disabled}, then 1.174 +per-user directories will be disabled. Otherwise, the string after 1.175 +\texttt{UserDir} gives the name of the subdirectory that Apache will 1.176 +look in under your home directory, for example \dirname{public\_html}. 1.177 + 1.178 +Your file access permissions may be too restrictive. The web server 1.179 +must be able to traverse your home directory and directories under 1.180 +your \dirname{public\_html} directory, and read files under the latter 1.181 +too. Here's a quick recipe to help you to make your permissions more 1.182 +appropriate. 1.183 +\begin{codesample2} 1.184 + chmod 755 ~ 1.185 + find ~/public_html -type d -print0 | xargs -0r chmod 755 1.186 + find ~/public_html -type f -print0 | xargs -0r chmod 644 1.187 +\end{codesample2} 1.188 + 1.189 +The other possibility with permissions is that you might get a 1.190 +completely empty window when you try to load the script. In this 1.191 +case, it's likely that your access permissions are \emph{too 1.192 + permissive}. Apache's \texttt{suexec} subsystem won't execute a 1.193 +script that's group-~or world-writable, for example. 1.194 + 1.195 +Your web server may be configured to disallow execution of CGI 1.196 +programs in your per-user web directory. Here's Apache's 1.197 +default per-user configuration from my Fedora system. 1.198 +\begin{codesample2} 1.199 + <Directory /home/*/public_html> 1.200 + AllowOverride FileInfo AuthConfig Limit 1.201 + Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec 1.202 + <Limit GET POST OPTIONS> 1.203 + Order allow,deny 1.204 + Allow from all 1.205 + </Limit> 1.206 + <LimitExcept GET POST OPTIONS> 1.207 + Order deny,allow 1.208 + Deny from all 1.209 + </LimitExcept> 1.210 + </Directory> 1.211 +\end{codesample2} 1.212 +If you find a similar-looking \texttt{Directory} group in your Apache 1.213 +configuration, the directive to look at inside it is \texttt{Options}. 1.214 +Add \texttt{ExecCGI} to the end of this list if it's missing, and 1.215 +restart the web server. 1.216 + 1.217 +If you find that Apache serves you the text of the CGI script instead 1.218 +of executing it, you may need to either uncomment (if already present) 1.219 +or add a directive like this. 1.220 +\begin{codesample2} 1.221 + AddHandler cgi-script .cgi 1.222 +\end{codesample2} 1.223 + 1.224 +The next possibility is that you might be served with a colourful 1.225 +Python backtrace claiming that it can't import a 1.226 +\texttt{mercurial}-related module. This is actually progress! The 1.227 +server is now capable of executing your CGI script. This error is 1.228 +only likely to occur if you're running a private installation of 1.229 +Mercurial, instead of a system-wide version. Remember that the web 1.230 +server runs the CGI program without any of the environment variables 1.231 +that you take for granted in an interactive session. If this error 1.232 +happens to you, edit your copy of \sfilename{hgweb.cgi} and follow the 1.233 +directions inside it to correctly set your \envar{PYTHONPATH} 1.234 +environment variable. 1.235 + 1.236 +Finally, you are \emph{certain} to by served with another colourful 1.237 +Python backtrace: this one will complain that it can't find 1.238 +\dirname{/path/to/repository}. Edit your \sfilename{hgweb.cgi} script 1.239 +and replace the \dirname{/path/to/repository} string with the complete 1.240 +path to the repository you want to serve up. 1.241 + 1.242 +At this point, when you try to reload the page, you should be 1.243 +presented with a nice HTML view of your repository's history. Whew! 1.244 + 1.245 +\subsubsection{Configuring lighttpd} 1.246 + 1.247 +To be exhaustive in my experiments, I tried configuring the 1.248 +increasingly popular \texttt{lighttpd} web server to serve the same 1.249 +repository as I described with Apache above. I had already overcome 1.250 +all of the problems I outlined with Apache, many of which are not 1.251 +server-specific. As a result, I was fairly sure that my file and 1.252 +directory permissions were good, and that my \sfilename{hgweb.cgi} 1.253 +script was properly edited. 1.254 + 1.255 +Once I had Apache running, getting \texttt{lighttpd} to serve the 1.256 +repository was a snap. I first had to edit the \texttt{mod\_access} 1.257 +section of the config file to enable \texttt{mod\_cgi} and 1.258 +\texttt{mod\_userdir}, both of which were disabled by default on my 1.259 +system. I then added a few lines to the end of the config file, to 1.260 +configure these modules. 1.261 +\begin{codesample2} 1.262 + userdir.path = "public_html" 1.263 + cgi.assign = ( ".cgi" => "" ) 1.264 +\end{codesample2} 1.265 +With this done, \texttt{lighttpd} ran immediately for me. If I had 1.266 +configured \texttt{lighttpd} before Apache, I'd almost certainly have 1.267 +run into many of the same system-level configuration problems as I did 1.268 +with Apache. However, I found \texttt{lighttpd} to be noticeably 1.269 +easier to configure than Apache, even though I've used Apache for over 1.270 +a decade, and this was my first exposure to \texttt{lighttpd}. 1.271 1.272 1.273 %%% Local Variables: