hgbook
view es/collab.tex @ 427:4a1dc5e8e2ff
Started ssh protocol translation
| author | Igor TAmara <igor@tamarapatino.org> |
|---|---|
| date | Sun Nov 23 23:15:17 2008 -0500 (2008-11-23) |
| parents | 7f5d542be96b |
| children | 35370f1551a7 |
line source
1 \chapter{Colaborar con otros}
2 \label{cha:collab}
4 Debido a su naturaleza descentralizada, Mercurial no impone política
5 alguna de cómo deben trabajar los grupos de personas. Sin embargo, si
6 usted es nuevo al control distribuido de versiones, es bueno tener
7 herramientas y ejemplos a la mano al pensar en posibles modelos de
8 flujo de trabajo.
10 \section{La interfaz web de Mercurial}
12 Mercurial tiene una poderosa interfaz web que provee bastantes
13 capacidades útiles.
15 Para uso interactivo, la interfaz le permite visualizar uno o varios
16 repositorios. Puede ver la historia de un repositorio, examinar cada
17 cambio(comentarios y diferencias), y ver los contenidos de cada
18 directorio y fichero.
20 Adicionalmente la interfaz provee feeds de RSS de los cambios de los
21 repositorios. Que le permite ``subscribirse''a un repositorio usando
22 su herramienta de lectura de feeds favorita, y ser notificado
23 automáticamente de la actividad en el repositorio tan pronto como
24 sucede. Me gusta mucho más este modelo que el estar suscrito a una
25 lista de correo a la cual se envían las notificaciones, dado que no
26 requiere configuración adicional de parte de quien sea que está
27 administrando el repositorio.
29 La interfaz web también permite clonar repositorios a los usuarios
30 remotos, jalar cambios, y (cuando el servidor está configurado para
31 permitirlo) publicar cambios en el mismo. El protocolo de tunneling
32 de Mercurial comprime datos agresivamente, de forma que trabaja
33 eficientemente incluso con conexiones de red con poco ancho de banda.
35 La forma más sencilla de iniciarse con la interfaz web es usar su
36 navegador para visitar un repositorio existente, como por ejemplo el
37 repositorio principal de Mercurial \url{http://www.selenic.com/repo/hg?style=gitweb}.
39 Si está interesado en proveer una interfaz web a sus propios
40 repositorios, Mercurial provee dos formas de hacerlo. La primera es
41 usando la orden \hgcmd{serve}, que está enfocada a servir ``de forma
42 liviana'' y por intervalos cortos. Para más detalles de cómo usar
43 esta orden vea la sección~\ref{sec:collab:serve} más adelante. Si
44 tiene un repositorio que desea hacer permanente, Mercurial tiene
45 soporte embebido del \command{ssh} para publicar cambios con seguridad
46 al repositorio central, como se documenta en la
47 sección~\ref{sec:collab:ssh}. Es muy usual que se publique una copia
48 de sólo lectura en el repositorio que está corriendo sobre HTTP usando
49 CGI, como en la sección~\ref{sec:collab:cgi}. Publicar sobre HTTP
50 satisface las necesidades de la gente que no tiene permisos de
51 publicación y de aquellos que quieren usar navegadores web para
52 visualizar la historia del repositorio.
54 \subsection{Trabajo con muchas ramas}
56 Los proyectos de cierta talla tienden naturlamente a progresar de
57 forma simultánea en varios frentes. En el caso del software, es común
58 que un proyecto tenga versiones periódicas oficiales. Una versión
59 puede entrar a ``modo mantenimiento'' por un tiempo después de su
60 primera publicación; las versiones de mantenimiento tienden a contener
61 solamente arreglos de fallos, pero no nuevas características. En
62 paralelo con las versiones de mantenimiento puede haber una o muchas
63 versiones futuras pueden estar en desarrollo. La gente usa normalmente
64 la palabra ``rama'' para referirse a una de las direcciones
65 ligeramente distintas en las cuales procede el desarrollo.
67 Mercurial está especialmente preparado para administrar un buen número
68 de ramas simultáneas pero no idénticas. Cada ``dirección de
69 desarrollo'' puede vivir en su propio repositorio central, y puede
70 mezclar los cambios de una a otra de acuerdo con las necesidades. Dado
71 que los repositorios son independientes, uno del otro, los cambios
72 inestables de una rama de desarrollo nunca afectarán una rama estable
73 a menos que alguien explícitamente mezcle los cambios.
75 A continuación un ejemplo de cómo podría hacerse esto en la
76 práctica. Digamos que tiene una ``rama principal'' en un servidor
77 central.
78 \interaction{branching.init}
79 Alguien lo clona, hace cambios locales, los prueba, y los publica allí
80 mismo.
82 Una vez que la rama principal alcanza una estado de versión se puede
83 usar la orden \hgcmd{tag} para dar un nombre permanente a la revisión.
84 \interaction{branching.tag}
85 Digamos que en la rama principal ocurre más desarrollo.
86 \interaction{branching.main}
87 Cuando se usa la etiqueta con que se identificó la versión, la gente
88 puede clonar el repositorio en cualquier momento en el futuro
89 empleando \hgcmd{update} para obtener una copia del directorio de
90 trabajo exacta como cuando se creó la etiqueta de la revisión que se
91 consignó.
92 \interaction{branching.update}
94 Adicionalmente, justo después de que la rama principal se etiquete,
95 alguien puede clonarla en el servidor a una nueva rama ``estable'',
96 también en el servidor.
97 \interaction{branching.clone}
99 Alguien que requiera hacer un cambio en la rama estable puede clonar
100 \emph{ese} repositorio, hacer sus cambios, consignar y publicarlos
101 posteriormente al inicial.
102 \interaction{branching.stable}
103 Puesto que los repositorios de Mercurial son independientes, y que
104 Mercurial no mueve los cambios de un lado a otro automáticamente, las
105 ramas estable y principal están \emph{aisladas} la una de la otra.
106 Los cambios que haga en la rama principal no ``se filtran'' a la rama
107 estable o vice versa.
109 Es usual que los arreglos de fallos de la rama estable deban hacerse
110 aparecer en la rama principal también. En lugar de reescribir el
111 arreglo del fallo en la rama principal, puede jalar y mezclar los
112 cambios de la rama estable a la principal, Mercurial traerá tales
113 arreglos por usted.
114 \interaction{branching.merge}
115 La rama principal contendtrá aún los cambios que no están en la
116 estable y contendrá además todos los arreglos de fallos de la rama
117 estable. La rama estable permanece incólume a tales cambios.
119 \subsection{Ramas de Características}
121 En proyectos grandes, una forma efectiva de administrar los cambios es
122 dividir el equipo en grupos más pequeños. Cada grupo tiene una rama
123 compartida, clonada de una rama ``principal'' que conforma el proyecto
124 completo. Aquellos que trabajan en ramas individuales típicamente
125 están aislados de los desarrollos de otras ramas.
127 \begin{figure}[ht]
128 \centering
129 \grafix{feature-branches}
130 \caption{Ramas de Características}
131 \label{fig:collab:feature-branches}
132 \end{figure}
134 Cuando una rama particular alcanza un estado deseado, alguien del
135 equipo de características jala y fusiona de la rama principal hacia
136 la rama de características y publica posteriormente a la rama principal.
138 \subsection{El tren de publicación}
140 Algunos proyectos se organizan al estilo``tren'': Una versión se
141 planifica para ser liberada cada cierto tiempo, y las características
142 que estén listas cuando ha llegado el momento ``tren'', se incorporan.
144 Este modelo tiene cierta similitud a las ramas de características. La
145 diferencia es que cuando una característica pierde el tren, alguien en
146 el equipo de características jala y fusiona los cambios que se fueron
147 en la versión liberada hacia la rama de característica, y el trabajo
148 continúa sobre lo fusionado para que la característica logre estar en
149 la próxima versión.
151 \subsection{El modelo del kernel linux}
153 El desarrollo del Kernel Linux tiene una estructura jerárquica
154 bastante horizontal, rodeada de una nube de caos aparente. Dado que la
155 mayoría de desarrolladores usan \command{git}, una herramienta distribuida
156 de control de versiones con capacidades similares a Mercurial, resulta
157 de utilidad describir la forma en que el trabajo fluye en tal
158 ambiente; si le gustan las ideas, la aproximación se traduce bien
159 entre Git y Mercurial.
161 En el centro de la comunidad está Linus Torvalds, el creador de Linux.
162 Él publica un único repositorio que es considerado el árbol
163 ``oficial'' actual por la comunidad completa de
164 desarrolladores. Cualquiera puede clonar el árbol de Linus, pero él es
165 muy selectivo acerca de los árboles de los cuales jala.
167 Linus tiene varios ``lugartenientes confiables''. Como regla, él jala
168 todos los cambios que ellos publican, en la mayoría de los casos sin
169 siquiera revisarlos. Algunos de sus lugartenientes generalmente
170 aceptan ser los ``mantenedores'', responsables de subsistemas
171 específicos dentro del kernel. Si un hacker cualquiera desea hacer un
172 cambio a un subsistema y busca que termine en el árbol de Linus, debe
173 encontrar quién es el mantenedor del subsistema y solicitarle que
174 tenga en cuenta su cambio. Si el mantenedor revisa los cambios y está
175 de acuerdo en tomarlos, estos pasarán al árbol de Linus de acuerdo a
176 lo expuesto.
178 Cada lugarteniente tiene su forma particular de revisar, aceptar y
179 publicar los cambios; y para decidir cuando hacerlos presentes a
180 Linus. Adicionalmente existen varias ramas conocidas que mucha gente
181 usa para propósitos distintos. Por ejemplo, pocas personas mantienen
182 repositorios ``estables'' de versiones anteriores del kernel, a los
183 cuales aplican arreglos de fallos críticos necesarios. Algunos
184 mantenedores publican varios árboles: uno para cambios
185 experimentales; uno para cambios que van a ofrecer al mantenedor
186 principal; y así sucesivamente. Otros publican un solo árbol.
188 Este modelo tiene dos características notables. La primera es que son
189 de ``jalar exclusivamente''. Usted debe solicitar, convencer o
190 incluso rogar a otro desarrollador para que tome sus cabmios, porque
191 casi no hay árboles en los cuales más de una persona pueda publicar, y
192 no hay forma de publicar cambios en un árbol que otra persona controla.
194 El segundo está basado en reputación y meritocracia. Si usted es un
195 desconocido, Linus probablemente ignorará sus cambios, sin siquiera
196 responderle. Pero un mantenedor de un subsistema probablemente los
197 revisara, y los acogerá en caso de que aprueben su criterio de
198 aplicabilidad. A medida que usted ofrezca ``mejores'' cambios a un
199 mantenedor, habrá más posibilidad de que se confíe en su juicio y se
200 acepten los cambios. Si usted es reconocido y matiene una rama
201 durante bastante tiempo para algo que Linus no ha aceptado, personas
202 con intereses similares pueden jalar sus cambios regularmente para
203 estar al día con su trabajo.
205 La reputación y meritocracia no necesariamente es transversal entre
206 ``personas'' de diferentes subsistemas. Si usted es respetado pero es
207 un hacker en almacenamiento y trata de arreglar un fallo de redes,
208 tal cambio puede recibir un nivel de escrutinio de un mantenedor de
209 redes comparable con el que se le haría a un completo extraño.
211 Personas que vienen de proyectos con un ordenamiento distinto, sienten
212 que el proceso comparativamente caótico del Kernel Linux es
213 completamente lunático. Es objeto de los caprichos individuales; la
214 gente desecha cambios cuando lo desean; y la fase de desarrollo es
215 alucinante. A pesar de eso Linux es una pieza de software exitosa y
216 bien reconocida.
218 \subsection{Solamente jalar frente a colaboración pública}
220 Una fuente perpetua de discusiones en la comunidad de código abierto
221 yace en el modelo de desarrollo en el cual la gente solamente jala
222 cambios de otros ``es mejor que'' uno en el cual muchas personas
223 pueden publicar cambios a un repositorio compartido.
225 Tícamente los partidarios del modelo de publicar usan las herramientas
226 que se apegan a este modelo. Si usted usa una herramienta
227 centralizada de control de versiones como Subversion, no hay forma de
228 elegir qué modelo va a usar: La herramienta le ofrece publicación
229 compartida, y si desea hacer cualquier otra cosa, va a tener que
230 aplicar una aproximación artificial (tal como aplicar parches a mano).
232 Una buena herramienta distribuida de control de versiones, tal como
233 Mercurial soportará los dos modelos. Usted y sus colaboradores
234 pueden estructurar cómo trabajarán juntos basados en sus propias
235 necesidades y preferencias, sin depender de las peripecias que la
236 herramienta les obligue a hacer.
238 \subsection{Cuando la colaboración encuentra la administración ramificada}
240 Una vez que usted y su equipo configurar algunos repositorios
241 compartidos y comienzan a propagar cambios entre sus repositorios
242 locales y compartidos, comenzará a encarar un reto relacionado, pero
243 un poco distinto: Administrar las direcciones en las cuales su equipo
244 puede moverse. A pesar de que está intimamente ligado acerca de cómo
245 interactúa su equipo, es lo suficientemente denso para ameritar un
246 tratamiento en el capítulo~\ref{chap:branch}.
248 \section{Aspectos técnicos de la colaboración}
250 Lo que resta del capítulo lo dedicamos a las cuestiones de servir
251 datos a sus colaboradores.
253 \section{Compartir informalmente con \hgcmd{serve}}
254 \label{sec:collab:serve}
256 La orden \hgcmd{serve} de Mercurial satisface de forma espectacular
257 las necesidades de un grupo pequeño, acoplado y de corto
258 tiempo. Se constituye en una demostración de cómo se siente usar los
259 comandos usando la red.
261 Ejecute \hgcmd{serve} dentro de un repositorio, y en pocos segundos
262 iniciará un servidor HTTP especializado; aceptará conexiones desde
263 cualquier cliente y servirá datos de este repositorio mientrs lo
264 mantenga funcionando. Todo el que sepa el URL del servidor que ha
265 iniciado, y que puede comunicarse con su computador por la red, puede
266 usar un navegador web o Mercurial para leer datos del repositorio. Un
267 URL para una instancia de \hgcmd{serve} ejecutándose en un portátil
268 debería lucir algo \Verb|http://my-laptop.local:8000/|.
270 La orden \hgcmd{serve} \emph{no} es un servidor web de propósito
271 general. Solamente puede hacer dos cosas:
272 \begin{itemize}
273 \item Permitir que se pueda visualizar la historia del repositorio que
274 está sirviendo desde navegadores web.
275 \item Hablar el protocolo de conexión de Mercurial para que puedan hacer
276 \hgcmd{clone} o \hgcmd{pull} (jalar) cambios de tal repositorio.
277 \end{itemize}
278 En particular, \hgcmd{serve} no permitirá que los usuarios remotos
279 puedan \emph{modificar} su repositorio. Es de tipo solo lectura.
281 Si está comenzando con Mercurial, no hay nada que le impida usar
282 \hgcmd{serve} para servir un repositorio en su propio computador, y
283 usar posteriormente órdenes como \hgcmd{clone}, \hgcmd{incoming}, para
284 comunicarse con el servidor como si el repositorio estuviera alojado
285 remotamente. Lo que además puede ayudarle a adecuarse rápidamente para
286 usar comandos en repositorios alojados en la red.
288 \subsection{Cuestiones adicionales para tener en cuenta}
290 Dado que permite lectura sin autenticación a todos sus clientes,
291 debería usar \hgcmd{serve} exclusivamente en ambientes en los cuáles
292 no tenga problema en que otros vean, o en los cuales tenga control
293 completo acerca de quien puede acceder a su red y jalar cambios de su
294 repositorio.
296 La orden \hgcmd{serve} no tiene conocimiento acerca de programas
297 cortafuegos que puedan estar instalados en su sistema o en su red. No
298 puede detectar o controlar sus cortafuegos. Si otras personas no
299 pueden acceder a su instancia \hgcmd{serve}, lo siguiente que debería hacer
300 (\emph{después} de asegurarse que tienen el URL correcto) es verificar
301 su configuración de cortafuegos.
303 De forma predeterminada, \hgcmd{serve} escucha conexiones entrantes en
304 el puerto~8000. Si otro proceso está escuchando en tal puerto, usted
305 podrá especificar un puerto distinto para escuchar con la opción
306 \hgopt{serve}{-p} .
308 Normalmente, cuando se inicia \hgcmd{serve}, no imprime nada, lo cual
309 puede ser desconcertante. Si desea confirmar que en efecto está
310 ejecutándose correctamente, y darse cuenta qué URL debería enviar a
311 sus colaboradores, inícielo con la opción \hggopt{-v}.
313 \section{Uso del protocolo Secure Shell (ssh)}
314 \label{sec:collab:ssh}
316 Usted puede publicar y jalar cambios en la red de forma segura usando
317 el protocolo Secure Shell (\texttt{ssh}). Para usarlo satisfactoriamente,
318 tendrá que hacer algo de configuración a nivel de cliente o el
319 servidor.
321 Si no está familizarizado con ssh, es un protocolo de red que le permite
322 comunicarse con seguridad con otro computador. Para usarlo con
323 Mercurial, estará estableciendo una o más cuentas de usuario en un
324 servidor de forma tal que los usuarios remotos puedan entrar y
325 ejecutar órdenes.
327 (Si ssh le \emph{es} familiar, encontrará probablemente elemental una
328 porción del material a continuación.)
330 \subsection{Cómo leer y escribir URLs de ssh}
332 Los URLs de ssh tienden a lucir de la siguiente forma:
333 \begin{codesample2}
334 ssh://bos@hg.serpentine.com:22/hg/hgbook
335 \end{codesample2}
336 \begin{enumerate}
337 \item La parte ``\texttt{ssh://}'' indica a Mercurial que use el
338 protocolo ssh.
339 \item El componente ``\texttt{bos@}'' indica el nombre del usuario que
340 está entrando al servidor. Puede omitirl si el usuario remoto
341 coincide con el usuario local.
342 \item ``\texttt{hg.serpentine.com}'' es el nombre del servidor al cual
343 se desea entrar.
344 \item El ``:22'' identifica el número del puerto en el servidor al cual
345 se conectará. El predeterminado es el~22, así que solamente
346 necesitará especificar esa porción si \emph{no} está usando el
347 puerto~22.
348 \item La última porción del URL es la ruta local al repositorio en el
349 servidor.
350 \end{enumerate}
352 El componente de la ruta del URL para ssh es una fuente de confusión,
353 puesto que no hay una forma estándar para que las herramientas puedan
354 interpretarlo. Algunos programas se comportan de manera distinta a
355 otros cuando manipulan estas rutas. No es la situación ideal, pero
356 es muy poco probable que vaya a cambiar. Por favor lea los párrafos
357 siguientes cuidadosamente.
359 Mercurial trata la ruta al repositorio en el servidor como relativo al
360 directorio chasa del usuario remoto. Por ejemplo, si el usuario
361 \texttt{foo} en el servidor tiene el directorio casa
362 \dirname{/home/foo},
363 entonces un URL ssh que contenga en su ruta a \dirname{bar}
364 \emph{realmente} se refiere al directorio \dirname{/home/foo/bar}.
366 Si desea especificar una ruta relativa a otro directorio de usuario,
367 puede usar una ruta que comience con un caracter tildado, seguido del
368 nombre del usuario(llamémosle \texttt{otrousuario}, así
369 \begin{codesample2}
370 ssh://server/~otrousuario/hg/repo
371 \end{codesample2}
373 Y si realmente desea especifica una ruta \emph{absoluta} en el
374 servidor, comience con el componente de la ruta con dos barras como
375 en el siguiente ejemplo:
376 \begin{codesample2}
377 ssh://server//absolute/path
378 \end{codesample2}
380 \subsection{Encontrar un cliente ssh para su sistema}
382 Casi todos los sistemas tipo Unix vienen con OpenSSH preinstalado. Si
383 usted está usando un sistema de estos, ejecute \Verb|which ssh| para
384 identificar dónde está instalada la orden \command{ssh} (usualmente
385 estará en \dirname{/usr/bin}). Si por casualidad no está presente,
386 vea la documentación de sus sistema para lograr instalarlo.
388 En Windows, tendrá que escoger primero un cliente adecuado para
389 descargarlo. Hay dos alternativas:
390 \begin{itemize}
391 \item El excelente paquete PuTTY~\cite{web:putty} de Simon Tatham, que
392 ofrece un suite completo de órdenes de cliente ssh.
393 \item Si tiene alta tolerancia al dolor, puede usar el porte de Cygwin
394 para OpenSSH.
395 \end{itemize}
396 En cualquier caso, tendrá que editar su fichero \hgini\ para indicarle
397 a Mercurial dónde encontrar la orden real del cliente. Por ejemplo, si
398 está usando PuTTY, tendrá que usar la orden \command{plink} como un
399 cliente de línea de órdenes.
400 \begin{codesample2}
401 [ui]
402 ssh = C:/ruta/a/plink.exe -ssh -i "C:/ruta/a/mi/llave/privada"
403 \end{codesample2}
405 \begin{note}
406 La ruta a \command{plink} no debería contener espacios o caracteres
407 en blanco, o Mercurial no podrá encontrarlo correctamente (por lo
408 tanto, probablemente no sería buena idea colocarlo en
409 \dirname{C:\\Program Files}
410 \end{note}
412 \subsection{Generar un par de llaves}
414 Para evitar la necesidad de teclera una clave de forma repetitiva cada
415 vez que necesita usar el cliente, recomiendo generar un par de llaves.
416 En un sistema tipo Unix, la orden \command{ssh-keygen} también se
417 comportará bien. En Windows, si está usando PuTTY, la orden
418 \command{puttygen} es la que necesitará.
420 Cuando genera un par de llaves, se aconseja \emph{comedidamente}
421 protegerlas con una frase de clave. (La única oportunidad en la cual
422 usted querría identificarse una única vez, es cuando está usando
423 el protocolo ssh para tareas automatizadas en una red segura.)
425 No basta con generar un par de llaves. Se requiere adicionar una llave
426 pública al conjunto de llaves autorizadas para todos los usuarios
427 remotos que se vayan a autenticar. Para aquellos servidores que usen
428 OpenSSH(la gran mayoría), significará añadir la llave pública a la
429 lista en el fichero llamado \sfilename{authorized\_keys} en su
430 directorio \sdirname{.ssh}.
432 En sistemas tipo Unix, su llave pública tendrá la extensión
433 \filename{.pub}. Si usa \command{puttygen} en Windows, puede
434 guardar la llave pública en un fichero de su elección, o pegarla desde
435 la ventana en la cual se despliega directamente en el fichero
436 \sfilename{authorized\_keys}.
438 \subsection{Using an authentication agent}
440 An authentication agent is a daemon that stores passphrases in memory
441 (so it will forget passphrases if you log out and log back in again).
442 An ssh client will notice if it's running, and query it for a
443 passphrase. If there's no authentication agent running, or the agent
444 doesn't store the necessary passphrase, you'll have to type your
445 passphrase every time Mercurial tries to communicate with a server on
446 your behalf (e.g.~whenever you pull or push changes).
448 The downside of storing passphrases in an agent is that it's possible
449 for a well-prepared attacker to recover the plain text of your
450 passphrases, in some cases even if your system has been power-cycled.
451 You should make your own judgment as to whether this is an acceptable
452 risk. It certainly saves a lot of repeated typing.
454 On Unix-like systems, the agent is called \command{ssh-agent}, and
455 it's often run automatically for you when you log in. You'll need to
456 use the \command{ssh-add} command to add passphrases to the agent's
457 store. On Windows, if you're using PuTTY, the \command{pageant}
458 command acts as the agent. It adds an icon to your system tray that
459 will let you manage stored passphrases.
461 \subsection{Configuring the server side properly}
463 Because ssh can be fiddly to set up if you're new to it, there's a
464 variety of things that can go wrong. Add Mercurial on top, and
465 there's plenty more scope for head-scratching. Most of these
466 potential problems occur on the server side, not the client side. The
467 good news is that once you've gotten a configuration working, it will
468 usually continue to work indefinitely.
470 Before you try using Mercurial to talk to an ssh server, it's best to
471 make sure that you can use the normal \command{ssh} or \command{putty}
472 command to talk to the server first. If you run into problems with
473 using these commands directly, Mercurial surely won't work. Worse, it
474 will obscure the underlying problem. Any time you want to debug
475 ssh-related Mercurial problems, you should drop back to making sure
476 that plain ssh client commands work first, \emph{before} you worry
477 about whether there's a problem with Mercurial.
479 The first thing to be sure of on the server side is that you can
480 actually log in from another machine at all. If you can't use
481 \command{ssh} or \command{putty} to log in, the error message you get
482 may give you a few hints as to what's wrong. The most common problems
483 are as follows.
484 \begin{itemize}
485 \item If you get a ``connection refused'' error, either there isn't an
486 SSH daemon running on the server at all, or it's inaccessible due to
487 firewall configuration.
488 \item If you get a ``no route to host'' error, you either have an
489 incorrect address for the server or a seriously locked down firewall
490 that won't admit its existence at all.
491 \item If you get a ``permission denied'' error, you may have mistyped
492 the username on the server, or you could have mistyped your key's
493 passphrase or the remote user's password.
494 \end{itemize}
495 In summary, if you're having trouble talking to the server's ssh
496 daemon, first make sure that one is running at all. On many systems
497 it will be installed, but disabled, by default. Once you're done with
498 this step, you should then check that the server's firewall is
499 configured to allow incoming connections on the port the ssh daemon is
500 listening on (usually~22). Don't worry about more exotic
501 possibilities for misconfiguration until you've checked these two
502 first.
504 If you're using an authentication agent on the client side to store
505 passphrases for your keys, you ought to be able to log into the server
506 without being prompted for a passphrase or a password. If you're
507 prompted for a passphrase, there are a few possible culprits.
508 \begin{itemize}
509 \item You might have forgotten to use \command{ssh-add} or
510 \command{pageant} to store the passphrase.
511 \item You might have stored the passphrase for the wrong key.
512 \end{itemize}
513 If you're being prompted for the remote user's password, there are
514 another few possible problems to check.
515 \begin{itemize}
516 \item Either the user's home directory or their \sdirname{.ssh}
517 directory might have excessively liberal permissions. As a result,
518 the ssh daemon will not trust or read their
519 \sfilename{authorized\_keys} file. For example, a group-writable
520 home or \sdirname{.ssh} directory will often cause this symptom.
521 \item The user's \sfilename{authorized\_keys} file may have a problem.
522 If anyone other than the user owns or can write to that file, the
523 ssh daemon will not trust or read it.
524 \end{itemize}
526 In the ideal world, you should be able to run the following command
527 successfully, and it should print exactly one line of output, the
528 current date and time.
529 \begin{codesample2}
530 ssh myserver date
531 \end{codesample2}
533 If, on your server, you have login scripts that print banners or other
534 junk even when running non-interactive commands like this, you should
535 fix them before you continue, so that they only print output if
536 they're run interactively. Otherwise these banners will at least
537 clutter up Mercurial's output. Worse, they could potentially cause
538 problems with running Mercurial commands remotely. Mercurial makes
539 tries to detect and ignore banners in non-interactive \command{ssh}
540 sessions, but it is not foolproof. (If you're editing your login
541 scripts on your server, the usual way to see if a login script is
542 running in an interactive shell is to check the return code from the
543 command \Verb|tty -s|.)
545 Once you've verified that plain old ssh is working with your server,
546 the next step is to ensure that Mercurial runs on the server. The
547 following command should run successfully:
548 \begin{codesample2}
549 ssh myserver hg version
550 \end{codesample2}
551 If you see an error message instead of normal \hgcmd{version} output,
552 this is usually because you haven't installed Mercurial to
553 \dirname{/usr/bin}. Don't worry if this is the case; you don't need
554 to do that. But you should check for a few possible problems.
555 \begin{itemize}
556 \item Is Mercurial really installed on the server at all? I know this
557 sounds trivial, but it's worth checking!
558 \item Maybe your shell's search path (usually set via the \envar{PATH}
559 environment variable) is simply misconfigured.
560 \item Perhaps your \envar{PATH} environment variable is only being set
561 to point to the location of the \command{hg} executable if the login
562 session is interactive. This can happen if you're setting the path
563 in the wrong shell login script. See your shell's documentation for
564 details.
565 \item The \envar{PYTHONPATH} environment variable may need to contain
566 the path to the Mercurial Python modules. It might not be set at
567 all; it could be incorrect; or it may be set only if the login is
568 interactive.
569 \end{itemize}
571 If you can run \hgcmd{version} over an ssh connection, well done!
572 You've got the server and client sorted out. You should now be able
573 to use Mercurial to access repositories hosted by that username on
574 that server. If you run into problems with Mercurial and ssh at this
575 point, try using the \hggopt{--debug} option to get a clearer picture
576 of what's going on.
578 \subsection{Using compression with ssh}
580 Mercurial does not compress data when it uses the ssh protocol,
581 because the ssh protocol can transparently compress data. However,
582 the default behaviour of ssh clients is \emph{not} to request
583 compression.
585 Over any network other than a fast LAN (even a wireless network),
586 using compression is likely to significantly speed up Mercurial's
587 network operations. For example, over a WAN, someone measured
588 compression as reducing the amount of time required to clone a
589 particularly large repository from~51 minutes to~17 minutes.
591 Both \command{ssh} and \command{plink} accept a \cmdopt{ssh}{-C}
592 option which turns on compression. You can easily edit your \hgrc\ to
593 enable compression for all of Mercurial's uses of the ssh protocol.
594 \begin{codesample2}
595 [ui]
596 ssh = ssh -C
597 \end{codesample2}
599 If you use \command{ssh}, you can configure it to always use
600 compression when talking to your server. To do this, edit your
601 \sfilename{.ssh/config} file (which may not yet exist), as follows.
602 \begin{codesample2}
603 Host hg
604 Compression yes
605 HostName hg.example.com
606 \end{codesample2}
607 This defines an alias, \texttt{hg}. When you use it on the
608 \command{ssh} command line or in a Mercurial \texttt{ssh}-protocol
609 URL, it will cause \command{ssh} to connect to \texttt{hg.example.com}
610 and use compression. This gives you both a shorter name to type and
611 compression, each of which is a good thing in its own right.
613 \section{Serving over HTTP using CGI}
614 \label{sec:collab:cgi}
616 Depending on how ambitious you are, configuring Mercurial's CGI
617 interface can take anything from a few moments to several hours.
619 We'll begin with the simplest of examples, and work our way towards a
620 more complex configuration. Even for the most basic case, you're
621 almost certainly going to need to read and modify your web server's
622 configuration.
624 \begin{note}
625 Configuring a web server is a complex, fiddly, and highly
626 system-dependent activity. I can't possibly give you instructions
627 that will cover anything like all of the cases you will encounter.
628 Please use your discretion and judgment in following the sections
629 below. Be prepared to make plenty of mistakes, and to spend a lot
630 of time reading your server's error logs.
631 \end{note}
633 \subsection{Web server configuration checklist}
635 Before you continue, do take a few moments to check a few aspects of
636 your system's setup.
638 \begin{enumerate}
639 \item Do you have a web server installed at all? Mac OS X ships with
640 Apache, but many other systems may not have a web server installed.
641 \item If you have a web server installed, is it actually running? On
642 most systems, even if one is present, it will be disabled by
643 default.
644 \item Is your server configured to allow you to run CGI programs in
645 the directory where you plan to do so? Most servers default to
646 explicitly disabling the ability to run CGI programs.
647 \end{enumerate}
649 If you don't have a web server installed, and don't have substantial
650 experience configuring Apache, you should consider using the
651 \texttt{lighttpd} web server instead of Apache. Apache has a
652 well-deserved reputation for baroque and confusing configuration.
653 While \texttt{lighttpd} is less capable in some ways than Apache, most
654 of these capabilities are not relevant to serving Mercurial
655 repositories. And \texttt{lighttpd} is undeniably \emph{much} easier
656 to get started with than Apache.
658 \subsection{Basic CGI configuration}
660 On Unix-like systems, it's common for users to have a subdirectory
661 named something like \dirname{public\_html} in their home directory,
662 from which they can serve up web pages. A file named \filename{foo}
663 in this directory will be accessible at a URL of the form
664 \texttt{http://www.example.com/\~username/foo}.
666 To get started, find the \sfilename{hgweb.cgi} script that should be
667 present in your Mercurial installation. If you can't quickly find a
668 local copy on your system, simply download one from the master
669 Mercurial repository at
670 \url{http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi}.
672 You'll need to copy this script into your \dirname{public\_html}
673 directory, and ensure that it's executable.
674 \begin{codesample2}
675 cp .../hgweb.cgi ~/public_html
676 chmod 755 ~/public_html/hgweb.cgi
677 \end{codesample2}
678 The \texttt{755} argument to \command{chmod} is a little more general
679 than just making the script executable: it ensures that the script is
680 executable by anyone, and that ``group'' and ``other'' write
681 permissions are \emph{not} set. If you were to leave those write
682 permissions enabled, Apache's \texttt{suexec} subsystem would likely
683 refuse to execute the script. In fact, \texttt{suexec} also insists
684 that the \emph{directory} in which the script resides must not be
685 writable by others.
686 \begin{codesample2}
687 chmod 755 ~/public_html
688 \end{codesample2}
690 \subsubsection{What could \emph{possibly} go wrong?}
691 \label{sec:collab:wtf}
693 Once you've copied the CGI script into place, go into a web browser,
694 and try to open the URL \url{http://myhostname/~myuser/hgweb.cgi},
695 \emph{but} brace yourself for instant failure. There's a high
696 probability that trying to visit this URL will fail, and there are
697 many possible reasons for this. In fact, you're likely to stumble
698 over almost every one of the possible errors below, so please read
699 carefully. The following are all of the problems I ran into on a
700 system running Fedora~7, with a fresh installation of Apache, and a
701 user account that I created specially to perform this exercise.
703 Your web server may have per-user directories disabled. If you're
704 using Apache, search your config file for a \texttt{UserDir}
705 directive. If there's none present, per-user directories will be
706 disabled. If one exists, but its value is \texttt{disabled}, then
707 per-user directories will be disabled. Otherwise, the string after
708 \texttt{UserDir} gives the name of the subdirectory that Apache will
709 look in under your home directory, for example \dirname{public\_html}.
711 Your file access permissions may be too restrictive. The web server
712 must be able to traverse your home directory and directories under
713 your \dirname{public\_html} directory, and read files under the latter
714 too. Here's a quick recipe to help you to make your permissions more
715 appropriate.
716 \begin{codesample2}
717 chmod 755 ~
718 find ~/public_html -type d -print0 | xargs -0r chmod 755
719 find ~/public_html -type f -print0 | xargs -0r chmod 644
720 \end{codesample2}
722 The other possibility with permissions is that you might get a
723 completely empty window when you try to load the script. In this
724 case, it's likely that your access permissions are \emph{too
725 permissive}. Apache's \texttt{suexec} subsystem won't execute a
726 script that's group-~or world-writable, for example.
728 Your web server may be configured to disallow execution of CGI
729 programs in your per-user web directory. Here's Apache's
730 default per-user configuration from my Fedora system.
731 \begin{codesample2}
732 <Directory /home/*/public_html>
733 AllowOverride FileInfo AuthConfig Limit
734 Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec
735 <Limit GET POST OPTIONS>
736 Order allow,deny
737 Allow from all
738 </Limit>
739 <LimitExcept GET POST OPTIONS>
740 Order deny,allow
741 Deny from all
742 </LimitExcept>
743 </Directory>
744 \end{codesample2}
745 If you find a similar-looking \texttt{Directory} group in your Apache
746 configuration, the directive to look at inside it is \texttt{Options}.
747 Add \texttt{ExecCGI} to the end of this list if it's missing, and
748 restart the web server.
750 If you find that Apache serves you the text of the CGI script instead
751 of executing it, you may need to either uncomment (if already present)
752 or add a directive like this.
753 \begin{codesample2}
754 AddHandler cgi-script .cgi
755 \end{codesample2}
757 The next possibility is that you might be served with a colourful
758 Python backtrace claiming that it can't import a
759 \texttt{mercurial}-related module. This is actually progress! The
760 server is now capable of executing your CGI script. This error is
761 only likely to occur if you're running a private installation of
762 Mercurial, instead of a system-wide version. Remember that the web
763 server runs the CGI program without any of the environment variables
764 that you take for granted in an interactive session. If this error
765 happens to you, edit your copy of \sfilename{hgweb.cgi} and follow the
766 directions inside it to correctly set your \envar{PYTHONPATH}
767 environment variable.
769 Finally, you are \emph{certain} to by served with another colourful
770 Python backtrace: this one will complain that it can't find
771 \dirname{/path/to/repository}. Edit your \sfilename{hgweb.cgi} script
772 and replace the \dirname{/path/to/repository} string with the complete
773 path to the repository you want to serve up.
775 At this point, when you try to reload the page, you should be
776 presented with a nice HTML view of your repository's history. Whew!
778 \subsubsection{Configuring lighttpd}
780 To be exhaustive in my experiments, I tried configuring the
781 increasingly popular \texttt{lighttpd} web server to serve the same
782 repository as I described with Apache above. I had already overcome
783 all of the problems I outlined with Apache, many of which are not
784 server-specific. As a result, I was fairly sure that my file and
785 directory permissions were good, and that my \sfilename{hgweb.cgi}
786 script was properly edited.
788 Once I had Apache running, getting \texttt{lighttpd} to serve the
789 repository was a snap (in other words, even if you're trying to use
790 \texttt{lighttpd}, you should read the Apache section). I first had
791 to edit the \texttt{mod\_access} section of its config file to enable
792 \texttt{mod\_cgi} and \texttt{mod\_userdir}, both of which were
793 disabled by default on my system. I then added a few lines to the end
794 of the config file, to configure these modules.
795 \begin{codesample2}
796 userdir.path = "public_html"
797 cgi.assign = ( ".cgi" => "" )
798 \end{codesample2}
799 With this done, \texttt{lighttpd} ran immediately for me. If I had
800 configured \texttt{lighttpd} before Apache, I'd almost certainly have
801 run into many of the same system-level configuration problems as I did
802 with Apache. However, I found \texttt{lighttpd} to be noticeably
803 easier to configure than Apache, even though I've used Apache for over
804 a decade, and this was my first exposure to \texttt{lighttpd}.
806 \subsection{Sharing multiple repositories with one CGI script}
808 The \sfilename{hgweb.cgi} script only lets you publish a single
809 repository, which is an annoying restriction. If you want to publish
810 more than one without wracking yourself with multiple copies of the
811 same script, each with different names, a better choice is to use the
812 \sfilename{hgwebdir.cgi} script.
814 The procedure to configure \sfilename{hgwebdir.cgi} is only a little
815 more involved than for \sfilename{hgweb.cgi}. First, you must obtain
816 a copy of the script. If you don't have one handy, you can download a
817 copy from the master Mercurial repository at
818 \url{http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi}.
820 You'll need to copy this script into your \dirname{public\_html}
821 directory, and ensure that it's executable.
822 \begin{codesample2}
823 cp .../hgwebdir.cgi ~/public_html
824 chmod 755 ~/public_html ~/public_html/hgwebdir.cgi
825 \end{codesample2}
826 With basic configuration out of the way, try to visit
827 \url{http://myhostname/~myuser/hgwebdir.cgi} in your browser. It
828 should display an empty list of repositories. If you get a blank
829 window or error message, try walking through the list of potential
830 problems in section~\ref{sec:collab:wtf}.
832 The \sfilename{hgwebdir.cgi} script relies on an external
833 configuration file. By default, it searches for a file named
834 \sfilename{hgweb.config} in the same directory as itself. You'll need
835 to create this file, and make it world-readable. The format of the
836 file is similar to a Windows ``ini'' file, as understood by Python's
837 \texttt{ConfigParser}~\cite{web:configparser} module.
839 The easiest way to configure \sfilename{hgwebdir.cgi} is with a
840 section named \texttt{collections}. This will automatically publish
841 \emph{every} repository under the directories you name. The section
842 should look like this:
843 \begin{codesample2}
844 [collections]
845 /my/root = /my/root
846 \end{codesample2}
847 Mercurial interprets this by looking at the directory name on the
848 \emph{right} hand side of the ``\texttt{=}'' sign; finding
849 repositories in that directory hierarchy; and using the text on the
850 \emph{left} to strip off matching text from the names it will actually
851 list in the web interface. The remaining component of a path after
852 this stripping has occurred is called a ``virtual path''.
854 Given the example above, if we have a repository whose local path is
855 \dirname{/my/root/this/repo}, the CGI script will strip the leading
856 \dirname{/my/root} from the name, and publish the repository with a
857 virtual path of \dirname{this/repo}. If the base URL for our CGI
858 script is \url{http://myhostname/~myuser/hgwebdir.cgi}, the complete
859 URL for that repository will be
860 \url{http://myhostname/~myuser/hgwebdir.cgi/this/repo}.
862 If we replace \dirname{/my/root} on the left hand side of this example
863 with \dirname{/my}, then \sfilename{hgwebdir.cgi} will only strip off
864 \dirname{/my} from the repository name, and will give us a virtual
865 path of \dirname{root/this/repo} instead of \dirname{this/repo}.
867 The \sfilename{hgwebdir.cgi} script will recursively search each
868 directory listed in the \texttt{collections} section of its
869 configuration file, but it will \texttt{not} recurse into the
870 repositories it finds.
872 The \texttt{collections} mechanism makes it easy to publish many
873 repositories in a ``fire and forget'' manner. You only need to set up
874 the CGI script and configuration file one time. Afterwards, you can
875 publish or unpublish a repository at any time by simply moving it
876 into, or out of, the directory hierarchy in which you've configured
877 \sfilename{hgwebdir.cgi} to look.
879 \subsubsection{Explicitly specifying which repositories to publish}
881 In addition to the \texttt{collections} mechanism, the
882 \sfilename{hgwebdir.cgi} script allows you to publish a specific list
883 of repositories. To do so, create a \texttt{paths} section, with
884 contents of the following form.
885 \begin{codesample2}
886 [paths]
887 repo1 = /my/path/to/some/repo
888 repo2 = /some/path/to/another
889 \end{codesample2}
890 In this case, the virtual path (the component that will appear in a
891 URL) is on the left hand side of each definition, while the path to
892 the repository is on the right. Notice that there does not need to be
893 any relationship between the virtual path you choose and the location
894 of a repository in your filesystem.
896 If you wish, you can use both the \texttt{collections} and
897 \texttt{paths} mechanisms simultaneously in a single configuration
898 file.
900 \begin{note}
901 If multiple repositories have the same virtual path,
902 \sfilename{hgwebdir.cgi} will not report an error. Instead, it will
903 behave unpredictably.
904 \end{note}
906 \subsection{Downloading source archives}
908 Mercurial's web interface lets users download an archive of any
909 revision. This archive will contain a snapshot of the working
910 directory as of that revision, but it will not contain a copy of the
911 repository data.
913 By default, this feature is not enabled. To enable it, you'll need to
914 add an \rcitem{web}{allow\_archive} item to the \rcsection{web}
915 section of your \hgrc.
917 \subsection{Web configuration options}
919 Mercurial's web interfaces (the \hgcmd{serve} command, and the
920 \sfilename{hgweb.cgi} and \sfilename{hgwebdir.cgi} scripts) have a
921 number of configuration options that you can set. These belong in a
922 section named \rcsection{web}.
923 \begin{itemize}
924 \item[\rcitem{web}{allow\_archive}] Determines which (if any) archive
925 download mechanisms Mercurial supports. If you enable this
926 feature, users of the web interface will be able to download an
927 archive of whatever revision of a repository they are viewing.
928 To enable the archive feature, this item must take the form of a
929 sequence of words drawn from the list below.
930 \begin{itemize}
931 \item[\texttt{bz2}] A \command{tar} archive, compressed using
932 \texttt{bzip2} compression. This has the best compression ratio,
933 but uses the most CPU time on the server.
934 \item[\texttt{gz}] A \command{tar} archive, compressed using
935 \texttt{gzip} compression.
936 \item[\texttt{zip}] A \command{zip} archive, compressed using LZW
937 compression. This format has the worst compression ratio, but is
938 widely used in the Windows world.
939 \end{itemize}
940 If you provide an empty list, or don't have an
941 \rcitem{web}{allow\_archive} entry at all, this feature will be
942 disabled. Here is an example of how to enable all three supported
943 formats.
944 \begin{codesample4}
945 [web]
946 allow_archive = bz2 gz zip
947 \end{codesample4}
948 \item[\rcitem{web}{allowpull}] Boolean. Determines whether the web
949 interface allows remote users to \hgcmd{pull} and \hgcmd{clone} this
950 repository over~HTTP. If set to \texttt{no} or \texttt{false}, only
951 the ``human-oriented'' portion of the web interface is available.
952 \item[\rcitem{web}{contact}] String. A free-form (but preferably
953 brief) string identifying the person or group in charge of the
954 repository. This often contains the name and email address of a
955 person or mailing list. It often makes sense to place this entry in
956 a repository's own \sfilename{.hg/hgrc} file, but it can make sense
957 to use in a global \hgrc\ if every repository has a single
958 maintainer.
959 \item[\rcitem{web}{maxchanges}] Integer. The default maximum number
960 of changesets to display in a single page of output.
961 \item[\rcitem{web}{maxfiles}] Integer. The default maximum number
962 of modified files to display in a single page of output.
963 \item[\rcitem{web}{stripes}] Integer. If the web interface displays
964 alternating ``stripes'' to make it easier to visually align rows
965 when you are looking at a table, this number controls the number of
966 rows in each stripe.
967 \item[\rcitem{web}{style}] Controls the template Mercurial uses to
968 display the web interface. Mercurial ships with two web templates,
969 named \texttt{default} and \texttt{gitweb} (the latter is much more
970 visually attractive). You can also specify a custom template of
971 your own; see chapter~\ref{chap:template} for details. Here, you
972 can see how to enable the \texttt{gitweb} style.
973 \begin{codesample4}
974 [web]
975 style = gitweb
976 \end{codesample4}
977 \item[\rcitem{web}{templates}] Path. The directory in which to search
978 for template files. By default, Mercurial searches in the directory
979 in which it was installed.
980 \end{itemize}
981 If you are using \sfilename{hgwebdir.cgi}, you can place a few
982 configuration items in a \rcsection{web} section of the
983 \sfilename{hgweb.config} file instead of a \hgrc\ file, for
984 convenience. These items are \rcitem{web}{motd} and
985 \rcitem{web}{style}.
987 \subsubsection{Options specific to an individual repository}
989 A few \rcsection{web} configuration items ought to be placed in a
990 repository's local \sfilename{.hg/hgrc}, rather than a user's or
991 global \hgrc.
992 \begin{itemize}
993 \item[\rcitem{web}{description}] String. A free-form (but preferably
994 brief) string that describes the contents or purpose of the
995 repository.
996 \item[\rcitem{web}{name}] String. The name to use for the repository
997 in the web interface. This overrides the default name, which is the
998 last component of the repository's path.
999 \end{itemize}
1001 \subsubsection{Options specific to the \hgcmd{serve} command}
1003 Some of the items in the \rcsection{web} section of a \hgrc\ file are
1004 only for use with the \hgcmd{serve} command.
1005 \begin{itemize}
1006 \item[\rcitem{web}{accesslog}] Path. The name of a file into which to
1007 write an access log. By default, the \hgcmd{serve} command writes
1008 this information to standard output, not to a file. Log entries are
1009 written in the standard ``combined'' file format used by almost all
1010 web servers.
1011 \item[\rcitem{web}{address}] String. The local address on which the
1012 server should listen for incoming connections. By default, the
1013 server listens on all addresses.
1014 \item[\rcitem{web}{errorlog}] Path. The name of a file into which to
1015 write an error log. By default, the \hgcmd{serve} command writes this
1016 information to standard error, not to a file.
1017 \item[\rcitem{web}{ipv6}] Boolean. Whether to use the IPv6 protocol.
1018 By default, IPv6 is not used.
1019 \item[\rcitem{web}{port}] Integer. The TCP~port number on which the
1020 server should listen. The default port number used is~8000.
1021 \end{itemize}
1023 \subsubsection{Choosing the right \hgrc\ file to add \rcsection{web}
1024 items to}
1026 It is important to remember that a web server like Apache or
1027 \texttt{lighttpd} will run under a user~ID that is different to yours.
1028 CGI scripts run by your server, such as \sfilename{hgweb.cgi}, will
1029 usually also run under that user~ID.
1031 If you add \rcsection{web} items to your own personal \hgrc\ file, CGI
1032 scripts won't read that \hgrc\ file. Those settings will thus only
1033 affect the behaviour of the \hgcmd{serve} command when you run it. To
1034 cause CGI scripts to see your settings, either create a \hgrc\ file in
1035 the home directory of the user ID that runs your web server, or add
1036 those settings to a system-wide \hgrc\ file.
1039 %%% Local Variables:
1040 %%% mode: latex
1041 %%% TeX-master: "00book"
1042 %%% End: