Differences between revisions 1 and 24 (spanning 23 versions)
Revision 1 as of 2012-03-09 01:35:39
Size: 2804
Editor: AaronJensen
Comment: Creating page for installing HgWeb on Windows.
Revision 24 as of 2018-04-16 13:02:24
Size: 9999
Editor: PeterSuter
Comment: Mention [experimental] httppostargs
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
## page was renamed from HgWebInIISOnWindows
## page was renamed from HgWebOnWindows
Line 3: Line 5:
= Installing HgWeb on Windows = = Configuring HgWeb in IIS on Windows =
Line 5: Line 7:
This page describes how to get HgWeb running on Windows Vista/2008 and 7/2008 R2. This page describes how to get Hg``Web running on
 *
Windows Vista
 * Windows Server
2008
 * Wi
ndows 7
 * Windows Server
2008 R2
Line 9: Line 15:
== Installing the Python CGI Handler == == Creating the HgWeb Website ==

Line 12: Line 20:
Create a directory for the Hg``Web website. Open Internet Information Services manager. Right-click the '''Sites''' folder and choose '''Add Web Site'''. Fill in your site's settings. (The Physical path should be set to your Hg``Web website directory.) Click OK. Create an Hg``Web website in IIS. We'll call the path to this website's root directory {{{HGWEB_ROOT}}}.
Line 14: Line 22:
Select the Hg``Web website and double-click '''Handler Mappings'''. Click the '''Add Script Map...''' action from the Actions menu (its in the upper right corner). In the '''Add Script Map''' dialog box, enter {{{*.cgi}}} for Request Path, {{{C:\Python26\python.exe -u "%s"}}} for Executable, and {{{Python}}} for Name. Click OK. You will then be prompted to allow the new ISAPI extension. Click Yes. ''If you don't, you'll get 404 errors when you try and execute a cgi script.'' Create a web.config file in {{{HGWEB_ROOT}}}. Edit it to look like this:
Line 16: Line 24:
In your Hg``Web directory, create a text file named test.cgi. Edit it to contain the following text: {{{#!xml
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <handlers>
      <add name="Python" path="*.cgi" verb="*" modules="CgiModule" scriptProcessor="PYTHON_HOME\python.exe -u &quot;%s&quot;" resourceType="Unspecified" requireAccess="Script" />
    </handlers>
  </system.webServer>
</configuration>
}}}

You'll then need to enable the Python module. From a command prompt, run:

{{{#!cmd
> C:\Windows\system32\inetsrv\appcmd set config /section:isapiCgiRestriction /+"[path='C:\Python26\python.exe -u %22%s%22',description='Python',allowed='True']"
}}}

You should have everything configured to start running CGI scripts through Python. To test that it's working, create a {{{test.cgi}}} file in {{{HGWEB_ROOT}}}:
Line 25: Line 50:
Save the file. Open a web browser and go to this test.cgi file, e.g. `http://example.com/test.cgi`. If you see '''It Works!''', you've got the Python CGI handler installed correctly.  You can now install Hg``Web. Save the file. Hit the {{{test.cgi}}} file in your web browser. If you see '''It Works!''', you've got the Python CGI handler installed correctly.
Line 27: Line 52:
== Adding Mercurial to Python ==
Line 28: Line 54:
== Installing HgWeb == Create an empty file named {{{hgweb.config}}} in your Hg``Web root directory. This is where the Hg``Web configuration goes once everything is working.
Line 30: Line 56:
Create an empty file named {{{hgweb.config}}} in your Hg``Web root directory.

[[Download#Windows|Download]] and run the Mercurial '''''Python module installer''''' (it's the one whose description says "use this for running hgweb"). After installation, you should see {{{mercurial}}} and {{{hgext}}} directories in your {{{PYTHON_HOME\Lib\site-packages}}} directory. If you don't see those directories, you chose the wrong installer.
[[Download#Windows|Download]] and run the Mercurial '''Python module installer''' (it's the one whose description says "use this for running hgweb"). After installation, you should see {{{mercurial}}} and {{{hgext}}} directories in your {{{PYTHON_HOME\Lib\site-packages}}} directory. If you don't see those directories, you chose the wrong installer.
Line 39: Line 63:
config = "DRIVE:\PATH\TO\HGWEB\DIRECTORY\hgweb.config config = "HGWEB_ROOT\hgweb.config"
Line 42: Line 66:
You should now be able to browse to hgweb.cgi (e.g. `http://example.com/hgweb.cgi`) and see the Hg``Web interface. Hit the hgweb.cgi script in your web browse and you should see the Hg``Web interface.

== Configuring URL Rewrite Rules ==

Now, we need to create some URL rewrite rules so that URLs to your repositories don't have {{{hgweb.cgi}}} in them.

First, you'll need to [[http://www.iis.net/download/urlrewrite|download and install version 2 of the Url Rewrite Module]].

Once that is finished, edit the {{{HGWEB_ROOT\web.config}}} file and add the following {{{<rewrite>}}} section under {{{<system.webServer>}}}:

{{{#!xml
  <system.webServer>
    <rewrite>
      <rules>
        <rule name="rewrite to hgwebdir" patternSyntax="Wildcard">
          <match url="*" />
          <conditions logicalGrouping="MatchAll" trackAllCaptures="false">
            <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
          </conditions>
          <action type="Rewrite" url="hgweb.cgi/{R:1}" />
        </rule>
      </rules>
    </rewrite>
  </system.webServer>
}}}

You should now be able to hit your website ''without'' {{{hgweb.cgi}}} in the URL and see the Hg``Web UI.

== Authenticating Against Active Directory ==

Add the following to your Hg``Web's web.config, in the {{{/configuration/system.webServer/security/authentication}}} section:

{{{#!xml
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <security>
      <authentication>
        <basicAuthentication enabled="true" realm="YOUR_DOMAIN" defaultLogonDomain="YOUR_DOMAIN" />
        <anonymousAuthentication enabled="true" />
      </authentication>
    </security>
  </system.webServer>
</configuration>
}}}

Replace {{{YOUR_DOMAIN}}} with the name of your Windows domain. Anonymous authentication is enabled so you can support unrestricted repositories (e.g. {{{allow_push=*}}}).

You'll need to unlock the basic authentication configuration section so it can be configured in your web.config:

{{{#!bat
> C:\Windows\system32\inetsrv\appcmd unlock config /section:basicAuthentication
}}}

You can test that authentication is working by adding an {{{allow_push}}} setting to the repository's .hg\hgrc file '''on the server''':

{{{#!ini
allow_push = USERNAME
}}}

Commit a change an attempt a push. You should see a sequence like this:

{{{#!bash
> hg push
pushing to https://localhost:4301/cm
searching for changes
http authorization required
realm: YOUR_DOMAIN
user: USERNAME
password:
}}}

'''Warning''' Remember that basic authentication sends usernames and passwords over the network in the clear. Anyone on the network will be able to read the user's credentials. We strongly recommend securing connections with SSL. Generating an SSL certificate and assigning it to your Hg``Web website is beyond the scope of this article.

== File System Permissions ==

IIS starts CGI processes as the user being authenticated. For un-authenticated, anonymous users/requests, the CGI process is started as the website's application pool identity. For authenticated users/requests, the CGI process is started as the authenticated user. Make sure you set proper NTFS permissions on your server-side repositories. Anybody who needs read-only access should have '''Read & execute''', '''List folder contents''', and '''Read ''' permissions. Anybody who needs read/write access should have '''Modify''', '''Read & execute''', '''List folder contents''', '''Read''', and '''Write''' NTFS permissions. We recommend creating groups for each set of users for each repository, and grant the appropriate NTFS permissions to those groups. To grant someone permission, add them to the appropriate group.

== Running via ISAPI ==

While running ''hgweb.cgi'' is fairly easy, CGI is rather slow way of serving pages. If more speed is required you should consider using ISAPI. Basic steps are described in
[[http://selenic.com/repo/hg/file/5983de86462c/contrib/win32/hgwebdir_wsgi.py|contrib/win32/hgwebdir_wsgi.py]] in Mercurial repository and in [[http://www.eworldui.net/blog/post/2010/04/08/Setting-up-Mercurial-server-in-IIS7-using-a-ISAPI-module.aspx|blog post]] (
[[http://web.archive.org/web/20101027212430/http://eworldui.net/blog/post/2010/04/08/Setting-up-Mercurial-server-in-IIS7-using-a-ISAPI-module.aspx|wayback archive]]).

Please note that some combinations of Windows/IIS/Python/Mercurial will not work. For example Windows Server 2008 R2 64 bit with Python 2.6 32 bit and precompiled 32 bit Mercurial
are not working and result in '''Error 500''' and such message:

{{{
Failed to import callback module 'hgwebdir_wsgi'
The specified module could not be found.
}}}

This is probably because of mix of [[https://groups.google.com/forum/?fromgroups#!msg/isapi_wsgi-dev/A_orSF7CKB0/eGK4yCydy8IJ|involved CRTs]].

== Troubleshooting ==

=== I'm getting an HTTP 400: Bad request error. What's going on? ===

This happens when Mercurial sends more request headers than IIS can handle. IIS may return an error page that says {{{HTTP Error 400. The size of the request headers is too long.}}}

By default, IIS limits the entire request header (i.e. the total size of all the headers in the request) to 16,384 bytes. If you have a repository with a lot of heads/branches, you can easily exceed this limit.

This setting is controlled by the {{{MaxRequestBytes}}} [[http://support.microsoft.com/kb/820129|HTTP.sys registry setting]]. The default value is 16,384 bytes. The maximum value is 16,777,216 bytes (approximately 16MB).

To change this setting, in the {{{HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\HTTP\Parameters}}} registry key, add a {{{MaxRequestBytes DWORD}}} whose value is the number of bytes you'd like to allow for a request's headers. You'll then need to restart the HTTP service and the World Wide Web Publishing Service.

{{{
net stop w3svc
net stop http
net start http
net start w3svc
}}}

Alternatively a server-side hgrc setting `[experimental] httppostargs = true` can fix the problem in Mercurial. [https://bugzilla.mozilla.org/show_bug.cgi?id=1350285 Mozilla uses this].)

<<Anchor(SeeAlso)>>

== See also ==
 * PublishingRepositories for general info on repository publishing
 * [[http://vampirebasic.blogspot.com/2009/06/running-mercurial-on-windows.html|Vampire Basic Blog]] has a very good walkthrough on how to set up hgwebdir on IIS
 * [[http://www.jeremyskinner.co.uk/mercurial-on-iis7/|Setting up a Mercurial server under IIS7 on Windows Server 2008 R2]] covers IIS and includes pictures to illustrate the process
 * [[http://www.endswithsaurus.com/2010/05/setting-up-and-configuring-mercurial-in.html|Setting up and configuring Mercurial in a Windows/IIS/Active Directory environment]] is a series of 4 blog posts describing how to set up Mercurial publishing over IIS and Windows
 * [[http://hglabhq.com/|HgLab]] - Managed Mercurial Server for Windows with push and pull support, Active Directory integration, ACLs and repository browser and manager.

----
CategoryWeb CategoryHowTo CategoryTipsAndTricks

Configuring HgWeb in IIS on Windows

This page describes how to get HgWeb running on

  • Windows Vista
  • Windows Server 2008
  • Windows 7
  • Windows Server 2008 R2

1. Creating the HgWeb Website

Install Python 2.6. By default, this installs to C:\Python26. On this page, the Python installation folder is referred to as PYTHON_HOME.

Create an HgWeb website in IIS. We'll call the path to this website's root directory HGWEB_ROOT.

Create a web.config file in HGWEB_ROOT. Edit it to look like this:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <handlers>
      <add name="Python" path="*.cgi" verb="*" modules="CgiModule" scriptProcessor="PYTHON_HOME\python.exe -u &quot;%s&quot;" resourceType="Unspecified" requireAccess="Script" />
    </handlers>
  </system.webServer>
</configuration>

You'll then need to enable the Python module. From a command prompt, run:

> C:\Windows\system32\inetsrv\appcmd set config /section:isapiCgiRestriction /+"[path='C:\Python26\python.exe -u %22%s%22',description='Python',allowed='True']"

You should have everything configured to start running CGI scripts through Python. To test that it's working, create a test.cgi file in HGWEB_ROOT:

   1 print 'Status: 200 OK'
   2 print 'Content-Type: text/html'
   3 print
   4 print '<html><body><h1>It Works!</h1></body></html>'

Save the file. Hit the test.cgi file in your web browser. If you see It Works!, you've got the Python CGI handler installed correctly.

2. Adding Mercurial to Python

Create an empty file named hgweb.config in your HgWeb root directory. This is where the HgWeb configuration goes once everything is working.

Download and run the Mercurial Python module installer (it's the one whose description says "use this for running hgweb"). After installation, you should see mercurial and hgext directories in your PYTHON_HOME\Lib\site-packages directory. If you don't see those directories, you chose the wrong installer.

Download the hgweb.cgi script for your version of Mercurial. Browse the Mercurial source code. Click the the tag for your version, click Browse in the navigation menu, click the hgweb.cgi script, then right-click Raw from the navigation menu, choose Save As... and save the file into your HgWeb directory.

Open hgweb.cgi and change the value of the config variable to point to the hgweb.config file you created earlier:

   1 config = "HGWEB_ROOT\hgweb.config"

Hit the hgweb.cgi script in your web browse and you should see the HgWeb interface.

3. Configuring URL Rewrite Rules

Now, we need to create some URL rewrite rules so that URLs to your repositories don't have hgweb.cgi in them.

First, you'll need to download and install version 2 of the Url Rewrite Module.

Once that is finished, edit the HGWEB_ROOT\web.config file and add the following <rewrite> section under <system.webServer>:

  <system.webServer>
    <rewrite>
      <rules>
        <rule name="rewrite to hgwebdir" patternSyntax="Wildcard">
          <match url="*" />
          <conditions logicalGrouping="MatchAll" trackAllCaptures="false">
            <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
          </conditions>
          <action type="Rewrite" url="hgweb.cgi/{R:1}" />
        </rule>
      </rules>
    </rewrite>
  </system.webServer>

You should now be able to hit your website without hgweb.cgi in the URL and see the HgWeb UI.

4. Authenticating Against Active Directory

Add the following to your HgWeb's web.config, in the /configuration/system.webServer/security/authentication section:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <security>
      <authentication>
        <basicAuthentication enabled="true" realm="YOUR_DOMAIN" defaultLogonDomain="YOUR_DOMAIN" />
        <anonymousAuthentication enabled="true" />
      </authentication>
    </security>
  </system.webServer>
</configuration>

Replace YOUR_DOMAIN with the name of your Windows domain. Anonymous authentication is enabled so you can support unrestricted repositories (e.g. allow_push=*).

You'll need to unlock the basic authentication configuration section so it can be configured in your web.config:

> C:\Windows\system32\inetsrv\appcmd unlock config /section:basicAuthentication

You can test that authentication is working by adding an allow_push setting to the repository's .hg\hgrc file on the server:

allow_push = USERNAME

Commit a change an attempt a push. You should see a sequence like this:

> hg push
pushing to https://localhost:4301/cm
searching for changes
http authorization required
realm: YOUR_DOMAIN
user: USERNAME
password:

Warning Remember that basic authentication sends usernames and passwords over the network in the clear. Anyone on the network will be able to read the user's credentials. We strongly recommend securing connections with SSL. Generating an SSL certificate and assigning it to your HgWeb website is beyond the scope of this article.

5. File System Permissions

IIS starts CGI processes as the user being authenticated. For un-authenticated, anonymous users/requests, the CGI process is started as the website's application pool identity. For authenticated users/requests, the CGI process is started as the authenticated user. Make sure you set proper NTFS permissions on your server-side repositories. Anybody who needs read-only access should have Read & execute, List folder contents, and Read permissions. Anybody who needs read/write access should have Modify, Read & execute, List folder contents, Read, and Write NTFS permissions. We recommend creating groups for each set of users for each repository, and grant the appropriate NTFS permissions to those groups. To grant someone permission, add them to the appropriate group.

6. Running via ISAPI

While running hgweb.cgi is fairly easy, CGI is rather slow way of serving pages. If more speed is required you should consider using ISAPI. Basic steps are described in contrib/win32/hgwebdir_wsgi.py in Mercurial repository and in blog post ( wayback archive).

Please note that some combinations of Windows/IIS/Python/Mercurial will not work. For example Windows Server 2008 R2 64 bit with Python 2.6 32 bit and precompiled 32 bit Mercurial are not working and result in Error 500 and such message:

Failed to import callback module 'hgwebdir_wsgi'
The specified module could not be found.

This is probably because of mix of involved CRTs.

7. Troubleshooting

7.1. I'm getting an HTTP 400: Bad request error. What's going on?

This happens when Mercurial sends more request headers than IIS can handle. IIS may return an error page that says HTTP Error 400. The size of the request headers is too long.

By default, IIS limits the entire request header (i.e. the total size of all the headers in the request) to 16,384 bytes. If you have a repository with a lot of heads/branches, you can easily exceed this limit.

This setting is controlled by the MaxRequestBytes HTTP.sys registry setting. The default value is 16,384 bytes. The maximum value is 16,777,216 bytes (approximately 16MB).

To change this setting, in the HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\HTTP\Parameters registry key, add a MaxRequestBytes DWORD whose value is the number of bytes you'd like to allow for a request's headers. You'll then need to restart the HTTP service and the World Wide Web Publishing Service.

net stop w3svc
net stop http
net start http
net start w3svc

Alternatively a server-side hgrc setting [experimental] httppostargs = true can fix the problem in Mercurial. [https://bugzilla.mozilla.org/show_bug.cgi?id=1350285 Mozilla uses this].)

8. See also


CategoryWeb CategoryHowTo CategoryTipsAndTricks

HgWebInIisOnWindows (last edited 2018-04-16 13:04:02 by PeterSuter)