Fossil SCM

fossil-scm / www / server / windows / cgi.md
Source Blame History 115 lines
f146e21… drh 1 # Serving via IIS + CGI
f146e21… drh 2
f146e21… drh 3 ## This Is Not the Method You Are Looking For
f146e21… drh 4
f146e21… drh 5 Setting up CGI service under IIS is surprisingly complicated compared to
f146e21… drh 6 running Fossil as a CGI under most other operating systems. We recommend
f146e21… drh 7 that you use the simpler [reverse proxying method](./iis.md) instead
f146e21… drh 8 unless there is some compelling reason why that method cannot work for
f146e21… drh 9 you, such as its dependence on non-stock IIS extensions. (Keep in mind
f146e21… drh 10 that both extensions it requires are by Microsoft, not third parties!)
f146e21… drh 11
f146e21… drh 12 Once you’ve got this scheme working, it gives the same benefits as those
f146e21… drh 13 listed at the top of the linked-to document.
f146e21… drh 14
f146e21… drh 15 There is a small benefit you get from using CGI over reverse proxying on
f146e21… drh 16 other OSes, which is that the Fossil program only runs briefly in order
f146e21… drh 17 to serve each HTTP hit. Once the request is done, that Fossil instance
f146e21… drh 18 shuts back down, releasing all of its resources. You don’t need to keep
f146e21… drh 19 a background Fossil HTTP server running full-time to provide CGI-based
f146e21… drh 20 Fossil service.
f146e21… drh 21
f146e21… drh 22 You lose a lot of that benefit on Windows:
f146e21… drh 23
f146e21… drh 24 1. It only matters to start with on servers that are highly RAM
f146e21… drh 25 constrained. (Roughly ≤ 128 MiB.) Our configuration steps below
f146e21… drh 26 assume you’re using the Windows and IIS GUIs, which have RAM
f146e21… drh 27 requirements well in excess of this, making Fossil’s resource
f146e21… drh 28 requirements a drop in the bucket next to them. On the [Azure
f146e21… drh 29 B1s][b1s] virtual machine I used to prepare these instructions, the
f146e21… drh 30 Windows Server Manager GUI kept filling the VM’s 1 GiB of RAM
f146e21… drh 31 during feature installation and crashing. I had to upgrade the VM’s
f146e21… drh 32 RAM to 2 GiB just to get useful work done!
f146e21… drh 33
f146e21… drh 34 2. Process creation on Windows is [much more expensive][cp] than on the
f146e21… drh 35 other OSes Fossil runs on, so the benefits of firing up a Fossil
f146e21… drh 36 executable to process each HTTP request are partially swamped by the
f146e21… drh 37 overhead of doing so.
f146e21… drh 38
f146e21… drh 39 Therefore, unless you’re willing to replace all of the GUI configuration
f146e21… drh 40 steps below with command line equivalents, or shut the GUI down entirely
f146e21… drh 41 after configuring IIS, CGI is a much less compelling option on Windows.
f146e21… drh 42
f146e21… drh 43 **WARNING:** The following tutorial appears to fail with the current
f146e21… drh 44 (2019-08-17) version of Fossil, [apparently][fbug] due to an inability
f146e21… drh 45 of Fossil to detect that it’s being run in CGI mode.
f146e21… drh 46
f146e21… drh 47 [b1s]: https://azure.microsoft.com/en-us/blog/introducing-b-series-our-new-burstable-vm-size/
f146e21… drh 48 [cp]: https://stackoverflow.com/a/48244/142454
f146e21… drh 49 [fbug]: https://fossil-scm.org/forum/forumpost/de18dc32c0
f146e21… drh 50
f146e21… drh 51
f146e21… drh 52 ## Install IIS with CGI Support
f146e21… drh 53
f146e21… drh 54 The steps for this are identical to those for the [reverse proxying IIS
f146e21… drh 55 setup](./iis.md#install) except that you need to enable CGI in the last
f146e21… drh 56 step, since it isn’t installed by default. For Windows Server, the path
f146e21… drh 57 is:
f146e21… drh 58
f146e21… drh 59 ![Install CGI in IIS](./cgi-install-iis.png)
f146e21… drh 60
f146e21… drh 61 The path is similar on the consumer-focused versions of Windows, once
f146e21… drh 62 you get to that last step.
f146e21… drh 63
f146e21… drh 64
f146e21… drh 65 ## Setup
f146e21… drh 66
f146e21… drh 67 1. Install the Fossil executable to `c:\inetpub\wwwroot\bin` on the web
f146e21… drh 68 server. We can’t use an executable you might already have because IIS
f146e21… drh 69 runs under a separate user account, so we need to give that
f146e21… drh 70 executable special permissions, and that’s easiest to do under the
f146e21… drh 71 IIS tree:
f146e21… drh 72
f146e21… drh 73 ![IIS fossil.exe execute permission](./cgi-bin-perm.png)
f146e21… drh 74
f146e21… drh 75 2. In IIS Manager (a.k.a. `INETMGR`) drill down into the Sites folder
f146e21… drh 76 in the left-side pane and right-click your web site’s
f146e21… drh 77 configuration. (e.g. “Default Web Site”)
f146e21… drh 78
f146e21… drh 79 3. On that menu say “Add Virtual Directory.” Give it the alias “`cgi`”
f146e21… drh 80 and point it at a suitable directory, such as
f146e21… drh 81 “`c:\inetpub\wwwroot\cgi`”.
f146e21… drh 82
f146e21… drh 83 4. Double-click the “Handler Mappings” icon, then in the right-side
f146e21… drh 84 pane, click “Add Script Map...” Apply the following settings:
f146e21… drh 85
f146e21… drh 86 ![IIS script map dialog](./cgi-script-map.png)
f146e21… drh 87
f146e21… drh 88 The Executable path must point to the path we set up in step 1, not
f146e21… drh 89 to some other `fossil.exe` you may have elsewhere on your system.
f146e21… drh 90 You will need to change the default “`*.dll`” filter in the Open
f146e21… drh 91 dialog to “`*.exe`” in order to see it when browsing via the “`...`”
f146e21… drh 92 button.
f146e21… drh 93
f146e21… drh 94 5. Create a file called `repo.fslcgi` within the CGI directory you
f146e21… drh 95 chose in step 3, with a single line like this:
f146e21… drh 96
f146e21… drh 97 repository: c:\Users\SOMEONE\museum\repo.fossil
f146e21… drh 98
f146e21… drh 99 Give the actual path to the repository, of course.
f146e21… drh 100
f146e21… drh 101 6. Up at the top level of IIS Manager, double-click the “ISAPI and CGI
f146e21… drh 102 Restrictions” icon, then click “Add...” in the right-side pane.
f146e21… drh 103 Give the script you just created permission to execute:
f146e21… drh 104
f146e21… drh 105 ![IIS CGI execute permission](./cgi-exec-perm.png)
f146e21… drh 106
f146e21… drh 107 7. In the right-side pane, click “Restart” to apply this configuration,
f146e21… drh 108 then test it by visiting the newly-available URL in a browser:
f146e21… drh 109
f146e21… drh 110 http://localhost/cgi/repo.fslcgi
f146e21… drh 111
f146e21… drh 112 For more complicated setups such as “directory” mode, see [the generic
f146e21… drh 113 CGI instructions](../any/cgi.md).
f146e21… drh 114
f146e21… drh 115 *[Return to the top-level Fossil server article.](../)*

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button