# HG changeset patch # User Bryan O'Sullivan # Date 1177539824 25200 # Node ID 27b2c7c46af3f40124226d4cc2f88259e4669631 # Parent 8b599dcca58420ab216a9a61b28bfc8525768148 Start talking about basic CGI/HTTP configuration. diff -r 8b599dcca584 -r 27b2c7c46af3 en/collab.tex --- a/en/collab.tex Wed Apr 25 13:06:30 2007 -0700 +++ b/en/collab.tex Wed Apr 25 15:23:44 2007 -0700 @@ -328,7 +328,10 @@ \section{The technical side of sharing} -\subsection{Informal sharing with \hgcmd{serve}} +The remainder of this chapter is devoted to the question of serving +data to your collaborators. + +\section{Informal sharing with \hgcmd{serve}} \label{sec:collab:serve} Mercurial's \hgcmd{serve} command is wonderfully suited to small, @@ -362,7 +365,7 @@ This can help you to quickly get acquainted with using commands on network-hosted repositories. -\subsubsection{A few things to keep in mind} +\subsection{A few things to keep in mind} Because it provides unauthenticated read access to all clients, you should only use \hgcmd{serve} in an environment where you either don't @@ -386,7 +389,7 @@ correctly, and find out what URL you should send to your collaborators, start it with the \hggopt{-v} option. -\subsection{Using the Secure Shell (ssh) protocol} +\section{Using the Secure Shell (ssh) protocol} \label{sec:collab:ssh} You can pull and push changes securely over a network connection using @@ -402,7 +405,7 @@ (If you \emph{are} familiar with ssh, you'll probably find some of the material that follows to be elementary in nature.) -\subsubsection{How to read and write ssh URLs} +\subsection{How to read and write ssh URLs} An ssh URL tends to look like this: \begin{codesample2} @@ -449,7 +452,7 @@ ssh://server//absolute/path \end{codesample2} -\subsubsection{Finding an ssh client for your system} +\subsection{Finding an ssh client for your system} Almost every Unix-like system comes with OpenSSH preinstalled. If you're using such a system, run \Verb|which ssh| to find out if @@ -482,7 +485,7 @@ idea). \end{note} -\subsubsection{Generating a key pair} +\subsection{Generating a key pair} To avoid the need to repetitively type a password every time you need to use your ssh client, I recommend generating a key pair. On a @@ -508,7 +511,7 @@ window it's displayed in straight into the \sfilename{authorized\_keys} file. -\subsubsection{Using an authentication agent} +\subsection{Using an authentication agent} An authentication agent is a daemon that stores passphrases in memory (so it will forget passphrases if you log out and log back in again). @@ -531,7 +534,7 @@ command acts as the agent. It adds an icon to your system tray that will let you manage stored passphrases. -\subsubsection{Configuring the server side properly} +\subsection{Configuring the server side properly} Because ssh can be fiddly to set up if you're new to it, there's a variety of things that can go wrong. Add Mercurial on top, and @@ -648,7 +651,7 @@ point, try using the \hggopt{--debug} option to get a clearer picture of what's going on. -\subsubsection{Using compression with ssh} +\subsection{Using compression with ssh} Mercurial does not compress data when it uses the ssh protocol, because the ssh protocol can transparently compress data. However, @@ -683,9 +686,185 @@ and use compression. This gives you both a shorter name to type and compression, each of which is a good thing in its own right. -\subsection{Serving over HTTP with a CGI script} +\section{Serving over HTTP using CGI} \label{sec:collab:cgi} +Depending on how ambitious you are, configuring Mercurial's CGI +interface can take anything from a few moments to several hours. + +We'll begin with the simplest of examples, and work our way towards a +more complex configuration. Even for the most basic case, you're +almost certainly going to need to read and modify your web server's +configuration. + +\begin{note} + Configuring a web server is a complex, fiddly, and highly + system-dependent activity. I can't possibly give you instructions + that will cover anything like all of the cases you will encounter. + Please use your discretion and judgment in following the sections + below. Be prepared to make plenty of mistakes, and to spend a lot + of time reading your server's error logs. +\end{note} + +\subsection{Web server configuration checklist} + +Before you continue, do take a few moments to check a few aspects of +your system's setup. + +\begin{enumerate} +\item Do you have a web server installed at all? Mac OS X ships with + Apache, but many other systems may not have a web server installed. +\item If you have a web server installed, is it actually running? On + most systems, even if one is present, it will be disabled by + default. +\item Is your server configured to allow you to run CGI programs in + the directory where you plan to do so? Most servers default to + explicitly disabling the ability to run CGI programs. +\end{enumerate} + +If you don't have a web server installed, and don't have substantial +experience configuring Apache, you should consider using the +\texttt{lighttpd} web server instead of Apache. Apache has a +well-deserved reputation for baroque and confusing configuration. +While \texttt{lighttpd} is less capable in some ways than Apache, most +of these capabilities are not relevant to serving Mercurial +repositories. And \texttt{lighttpd} is undeniably \emph{much} easier +to get started with than Apache. + +\subsection{Basic CGI configuration} + +On Unix-like systems, it's common for users to have a subdirectory +named something like \dirname{public\_html} in their home directory, +from which they can serve up web pages. A file named \filename{foo} +in this directory will be accessible at a URL of the form +\texttt{http://www.example.com/\~username/foo}. + +To get started, find the \sfilename{hgweb.cgi} script that should be +present in your Mercurial installation. If you can't quickly find a +local copy on your system, simply download one from the master +Mercurial repository at +\url{http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi}. + +You'll need to copy this script into your \dirname{public\_html} +directory, and ensure that it's executable. +\begin{codesample2} + cp .../hgweb.cgi ~/public_html + chmod +x ~/public_html/hgweb.cgi +\end{codesample2} + +\subsubsection{What could \emph{possibly} go wrong?} + +Once you've copied the CGI script into place, go into a web browser, +and try to open the URL \url{http://myhostname/~myuser/hgweb.cgi}, +\emph{but} brace yourself for instant failure. There's a high +probability that trying to visit this URL will fail, and there are +many possible reasons for this. In fact, you're likely to stumble +over almost every one of the possible errors below, so please read +carefully. The following are all of the problems I ran into on a +system running Fedora~7, with a fresh installation of Apache, and a +user account that I created specially. + +Your web server may have per-user directories disabled. If you're +using Apache, search your config file for a \texttt{UserDir} +directive. If there's none present, per-user directories will be +disabled. If one exists, but its value is \texttt{disabled}, then +per-user directories will be disabled. Otherwise, the string after +\texttt{UserDir} gives the name of the subdirectory that Apache will +look in under your home directory, for example \dirname{public\_html}. + +Your file access permissions may be too restrictive. The web server +must be able to traverse your home directory and directories under +your \dirname{public\_html} directory, and read files under the latter +too. Here's a quick recipe to help you to make your permissions more +appropriate. +\begin{codesample2} + chmod 755 ~ + find ~/public_html -type d -print0 | xargs -0r chmod 755 + find ~/public_html -type f -print0 | xargs -0r chmod 644 +\end{codesample2} + +The other possibility with permissions is that you might get a +completely empty window when you try to load the script. In this +case, it's likely that your access permissions are \emph{too + permissive}. Apache's \texttt{suexec} subsystem won't execute a +script that's group-~or world-writable, for example. + +Your web server may be configured to disallow execution of CGI +programs in your per-user web directory. Here's Apache's +default per-user configuration from my Fedora system. +\begin{codesample2} + + AllowOverride FileInfo AuthConfig Limit + Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec + + Order allow,deny + Allow from all + + + Order deny,allow + Deny from all + + +\end{codesample2} +If you find a similar-looking \texttt{Directory} group in your Apache +configuration, the directive to look at inside it is \texttt{Options}. +Add \texttt{ExecCGI} to the end of this list if it's missing, and +restart the web server. + +If you find that Apache serves you the text of the CGI script instead +of executing it, you may need to either uncomment (if already present) +or add a directive like this. +\begin{codesample2} + AddHandler cgi-script .cgi +\end{codesample2} + +The next possibility is that you might be served with a colourful +Python backtrace claiming that it can't import a +\texttt{mercurial}-related module. This is actually progress! The +server is now capable of executing your CGI script. This error is +only likely to occur if you're running a private installation of +Mercurial, instead of a system-wide version. Remember that the web +server runs the CGI program without any of the environment variables +that you take for granted in an interactive session. If this error +happens to you, edit your copy of \sfilename{hgweb.cgi} and follow the +directions inside it to correctly set your \envar{PYTHONPATH} +environment variable. + +Finally, you are \emph{certain} to by served with another colourful +Python backtrace: this one will complain that it can't find +\dirname{/path/to/repository}. Edit your \sfilename{hgweb.cgi} script +and replace the \dirname{/path/to/repository} string with the complete +path to the repository you want to serve up. + +At this point, when you try to reload the page, you should be +presented with a nice HTML view of your repository's history. Whew! + +\subsubsection{Configuring lighttpd} + +To be exhaustive in my experiments, I tried configuring the +increasingly popular \texttt{lighttpd} web server to serve the same +repository as I described with Apache above. I had already overcome +all of the problems I outlined with Apache, many of which are not +server-specific. As a result, I was fairly sure that my file and +directory permissions were good, and that my \sfilename{hgweb.cgi} +script was properly edited. + +Once I had Apache running, getting \texttt{lighttpd} to serve the +repository was a snap. I first had to edit the \texttt{mod\_access} +section of the config file to enable \texttt{mod\_cgi} and +\texttt{mod\_userdir}, both of which were disabled by default on my +system. I then added a few lines to the end of the config file, to +configure these modules. +\begin{codesample2} + userdir.path = "public_html" + cgi.assign = ( ".cgi" => "" ) +\end{codesample2} +With this done, \texttt{lighttpd} ran immediately for me. If I had +configured \texttt{lighttpd} before Apache, I'd almost certainly have +run into many of the same system-level configuration problems as I did +with Apache. However, I found \texttt{lighttpd} to be noticeably +easier to configure than Apache, even though I've used Apache for over +a decade, and this was my first exposure to \texttt{lighttpd}. %%% Local Variables: