Last updated: Jun 12, 2004

Index
-------

  * Installing mod_mono
    o Prerrequisites
    o Assumptions
    o Step by step (everything in /usr!)
      -Tip: If mono was not installed in /usr

  * APPENDIX A: Typical configuration without virtual hosts
  * APPENDIX B: Configuration directives for mod_mono
  * APPENDIX C: Webapp file format
  * APPENDIX D: More information
  * CREDITS
  

Installing mod_mono
--------------------

  The following are instructions on getting mod_mono working with
  Apache, either 1.3 or 2. Once you set it up, Apache will be able to
  serve ASP.NET pages.

  * Prerrequisites
  -----------------
  You will need:

    * mono (http://www.go-mono.com)
    * apache 1.3 or 2 and its development package. Usually called
    apache2-dev, apache-dev...
    * Latest xsp and mod_mono tarballs (http://go-mono.com/download.html)

  * Assumptions
  -------------
  The next steps assume you have installed mono, xsp and apache in
  /usr. Notice that you will need to be root in order to run 'make
  install'.

  * Step by step (everything in /usr!)
  -------------------------------------
    1. Install mod_mono.

             tar xvfz mod_mono-X.Y.Z.tar.gz
             cd mod_mono-X.Y.Z
   (*)       ./configure --prefix=/usr
             make
             make install

       (*) If it complains about not finding apxs because you installed
       apache in a non-common directory or the configuration summary
       reports an apache version different from what you expected, use
       the --with-apxs argument. Example:

         ./configure --prefix=/usr --with-apxs=/usr/sbin/apxs

       (Apache 2 only) If you get errors while compiling due to apr.h
       header not found, you'll need to use the --with-apr-config option
       and provide the full path to 'apr-config':

         ./configure --prefix=/usr --with-apr-config=/usr/bin/apr-config

       After running 'make install', the module is installed in the
       proper location and the apache configuration file has been
       updated to load the module. apxs automatically adds this line (or
       similar) to httpd.conf if not already present:

         LoadModule mono_module modules/libmod_mono.so

    2. Configure apache.

       We're going to configure apache so that we can browse the samples
       installed by XSP under /usr/share/doc/xsp/test.

       Edit your httpd.conf file, which should be in /etc/httpd,
       /etc/apache, /etc/apache2...

       Add the following lines:

            Alias /demo "/usr/share/doc/xsp/test"
	    MonoApplications "/demo:/usr/share/doc/xsp/test"

       so that apache redirects requests from /demo to /demo/ and looks
       for everything requested as /demo/xxx under
       /usr/share/doc/xsp/test/xxx.Don't forget the quotes.

       For Apache 1.3 and, optionally, for Apache 2.0, add these lines:

            <Directory /usr/share/doc/xsp/test>
	           SetHandler mono
                   <IfModule mod_dir.c>
                         DirectoryIndex index.aspx
                   </IfModule>
            </Directory>

       If you are using Apache 2.0, you can use get the same results with
       this:

            <Location /demo>
	          SetHandler mono
            </Location>

	Take a look at Appendix A below for typical configuration
	samples and Appendix B for detailed descriptions on available
	configuration directives.

    3. Restart apache.
    4. Point your browser to http://127.0.0.1/demo/index.aspx

  Nice, huh?

      -TIP: If mono was not installed in /usr

      In this case, when running ./configure for mod_mono, you can do:

          ./configure --prefix=/usr --with-mono-prefix=/usr/local

      so that the default paths for locating mono and mod-mono-server
      are set to /usr/local/bin/mono and so on.

      

APPENDIX A: Typical configuration without virtual hosts
--------------------------------------------------------

  This samples assume that you have mono and mod-mono-server installed
  in /usr prefix. If you installed them in other place, take a look at
  Appendix C.

  In Apache 1.3 you will end up with something like:

      LoadModule mono_module /usr/lib/apache/1.3/libmod_mono.so
      AddModule mod_mono.c
      Alias /demo "/usr/share/doc/xsp/test"
      MonoApplications "/demo:/usr/share/doc/xsp/test"
      <Directory /usr/share/doc/xsp/test>
              SetHandler mono
              <IfModule mod_dir.c>
                    DirectoryIndex index.aspx
              </IfModule>
      </Directory>

  With Apache 2.0 you will have something like:

      LoadModule mono_module modules/libmod_mono.so
      Alias /demo "/usr/share/doc/xsp/test"
      MonoApplications "/demo:/usr/share/doc/xsp/test"
      <Directory /usr/share/doc/xsp/test>
              SetHandler mono
      </Directory>

  or like:

      LoadModule mono_module modules/libmod_mono.so
      Alias /demo "/usr/share/doc/xsp/test"
      MonoApplications "/demo:/usr/share/doc/xsp/test"
      <Location /demo>
              SetHandler mono
      </Location>

  If you don't want mod-mono-server to handle all the files, but only
  ASP.NET ones, you can replace the 'SetHandler mono' by:

       AddHandler mono .aspx .ascx .asax .ashx .config .cs .asmx

  but this will break PathInfo.

APPENDIX B: Configuration directives for mod_mono
---------------------------------------------------

  For the default values that have a path beginning with /usr, replace
  that /usr with your installation prefix if you installed elsewhere.
  
  These are the directives supported under both apache 1.3 and 2.0. You
  probably will never use those that have "used only when MonoRunXSP is
  True" in parenthesis unless you install mono and/or xsp in a different
  prefix from the one you used for mod_mono.

  MonoUnixSocket

    It accepts a file name as argument. That file will be a named pipe
    used to send/receive data from/to mod_mono to/from mod-mono-server.
    Default value: "/tmp/mod_mono_server".

  MonoRunXSP

    If the value is True, it tells mod_mono to spawn mod-mono-server.exe
    if it's not already running. If set to False, mod_mono won't do
    that.
    Default value: True

  MonoExecutablePath (used only when MonoRunXSP is True)

    The full path to mono executable.
    Default value: "/usr/bin/mono"

  MonoPath (used only when MonoRunXSP is True)

    This value will be used to set the MONO_PATH environment variable.
    Default value: ""

  MonoServerPath (used only when MonoRunXSP is True)

    The full path to mod-mono-server.exe.
    Default value: "/usr/bin/mod-mono-server.exe"

  MonoWapiDir

    The directory where mono runtime will create the ".wapi" directory
    used to emulate windows I/O. It's used to set MONO_SHARED_DIR.
    Default value: "/tmp"

  MonoDocumentRootDir

    Value passed in --root argument when running mod-mono-server. This
    tells mod-mono-server to change the directory to the value specified
    before doing anything else.

  MonoApplications (used only when MonoRunXSP is True)
  
    This value will be passed to mod-mono-server.exe in the
    --applications option. See xsp(1) manual page for details.

  MonoApplicationsConfigFile

    Adds application definitions from the  XML configuration file.
    See Appendix C for details on the file format.
    Default value: ""

  MonoApplicationsConfigDir

    Adds application definitions from all XML files found in the
    specified directory DIR. Files must have '.webapp' extension.
    Default value: ""

  Note that you must specify at least one of MonoApplications,
  MonoApplicationsConfigFile and MonoApplicationsConfigDir.


APPENDIX C: Webapp file format
---------------------------------

  The format of the .webapp files is:

      <apps>
         <web-application>
            <name>{appname}</name>
            <vhost>{virtual host for application}</vhost>
            <vport>{port for the application}</vport>
            <vpath>{virtual directory in apache}</vpath>
            <path>{physical path to aspx files}</path>
         </web-application>
      </apps>

  You  can include any number of <web-application> nodes, one per
  ASP.NET application to run.

  There's a sample.webapp file in the XSP samples directory.
  

APPENDIX D: More information
-----------------------------

  You can find more information in the manual pages of mono, xsp,
  mod-mono-server and mod_mono.

  Mono and ASP.NET section in the mono FAQ:

    http://www.go-mono.com/faq.html#mod_mono



CREDITS
--------

  Daniel Lopez Ridruejo <daniel @ rawbyte.com> 
  http://www.apacheworld.org

  Gonzalo Paniagua Javier <gonzalo @ ximian.com>

