Easy Configuration of Mod_Mono

When you installed XSP, a bunch of sample ASP.NET pages and web services were installed too. If the prefix used to configure XSP was /usr, the sample files are located in /usr/lib/xsp/test.

If your needs are not very complicated, all you need is to use AutoHosting AutoHosting , this basically means that you load the mod_mono.conf file, like this in your Apache configuration file:

Include /etc/apache2/mod_mono.conf

And applications will start to be served. To try it out, copy the /usr/lib/xsp/test directory to your Apache home (in OpenSUSE this is /srv/www/hdtocs).

It is recommended that you create a directory per application that you want served. This will allow you to xcopy deploy your applications from Windows to Linux if you want to.

For more detailed configuration and manual tuning keep reading.

Configuring Mod_Mono

Let's say you want those file to be available under the virtual path /test. Edit your httpd.conf file (hint: /etc/httpd, /etc/apache2) and append the following lines (remove the numbers ;-):

1   LoadModule mono_module modules/mod_mono.so
2   Alias /test "/usr/share/doc/xsp/test"
3   AddMonoApplications default "/test:/usr/share/doc/xsp/test"
4   
5       SetHandler mono
6   

In line 1, you might need to use the full path to mod_mono.so.

Now start/restart Apache and browse http://hostname/test/index.aspx (where hostname is the name of the server, or 127.0.0.1 if you're running Apache locally). If you cannot see the test page, go to the troubleshooting section, otherwise, welcome to ASP.NET!

Now for the explanation of what the lines you added to httpd.conf do. Line 1 tells apache to load mod_mono module. I use line 2 always so that apache can check files and directories and appends a trailing slash if someone requests /test.

The first argument to AddMonoApplications in line 3 will be discussed in next section. The second one is passed to mod-mono-server so that it knows that the /test virtual path corresponds to the physical path /usr/share/doc/xsp/test. Then in line 5, inside our chosen location, we tell apache that mod_mono will handle all requests down /test/.

Okay, it worked. But, what happened? When you started apache, mod_mono launched mod-mono-server. Later, when you requested any page under /test, mod_mono connected to mod-mono-server, forwarded the request data and retrieved the response that is sent to your browser. Finally, if you stop apache, mod_mono will tell mod-mono-server to die.

Here's an example if you're using virtual hosts:

   DocumentRoot /home/website/www
   ServerName www.example.com
   MonoApplications default "/:/home/website/www"
   MonoDocumentRootDir "/home/website/www"
   
     SetHandler mono
   

The SetHandler directive instructs Apache to invoke mod_mono for all pages in the Location in which the directive appears. You might have files in that directory that you want served like normal. In that case, remove the SetHandler directive and tell Apache which file extensions should be served with mod_mono using the AddHandler directive, as in:

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

If you use AddHandler you might want to let mod-mono-server know about your DirectoryIndex directive by doing something like this in your web.config file:

<
?xml version
="1.0"
 encoding
="utf-8"
?>



>




>





 key
="MonoServerDefaultIndexFiles"
 value
="mywierdindexfile.html,index.aspx"
 />



>




>

More on Applications

How do you go about making mod_mono handle several applications? Let's try the easiest option. You will need this in your httpd.conf:

1   LoadModule mono_module modules/mod_mono.so
2   Alias /test "/usr/share/doc/xsp/test"
3   Alias /personal "/home/user/mypages"
4   AddMonoApplications default "/test:/usr/share/doc/xsp/test,/personal:/home/user/mypages"
5   
6       SetHandler mono
7   
8   
9       SetHandler mono
10  

As you can see, it's just a matter of adding the line 3 (like line 2) and lines 8, 9, 10 (similar to 5, 6, 7). The other change is in AddMonoApplications (4), whose value got the new application virtual and physical paths appended.

Now let's focus on that line 4. Earlier in this document we said that mod_mono can run one or more instances of mod-mono-server and connects to it/them in order to dispatch ASP.NET requests. The first argument to AddMonoApplications and most of the other directives supported is an alias for a running mod-mono-server. Other directives allow omitting the first argument. In that case, 'default' is assumed. As you probably guessed:

AddMonoApplications default "/test:/usr/share/doc/xsp/test,/personal:/home/user/mypages"

	...is equivalent to...

AddMonoApplications default "/test:/usr/share/doc/xsp/test"
AddMonoApplications default "/personal:/home/user/mypages"

This way you can keep all the configuration related to an application in a separate file (Alias, AddMonoApplications, Location,...).

If you serve mod_mono applications in multiple virtual hosts, you can use this syntax:

AddMonoApplications default "www.example.com:/:/home/exampledotcom/www"
AddMonoApplications default "www.sample.com:/:/home/sampledotcom/www"

The above example instructs mod-mono-server to create two applications, one mapping http://www.example.com/ to /home/exampledotcom/www and the other mapping http://www.sample.com/ to /home/sampledotcom/www.

Multiple Applications, Multiple mod-mono-servers

You might want to run different applications in different instances of mod-mono-server.

There are a number of reasons for doing this:

• If you want to run a production and testing environments.
• You need completely separate Mono instances running.
• If you don't want Session or Application level objects to be shared among applications or that you want to set certain memory or CPU usage restrictions for an application.

Let's see the configuration needed to achieve this separation for the two applications in the previous example:

1   LoadModule mono_module modules/mod_mono.so
2   Alias /test "/usr/share/doc/xsp/test"
3   AddMonoApplications default "/test:/usr/share/doc/xsp/test"
4   
5       SetHandler mono
6   
7
8   Alias /personal "/home/user/mypages"
9   AddMonoApplications personal "/personal:/home/user/mypages"
11  
12      MonoSetServerAlias personal
13      SetHandler mono
14  

With this configuration mod_mono will start two instances of mod-mono-server whose aliases are 'default' and 'personal'. The 'default' instance will handle /test and the 'personal' instance will handle /personal. Every time mod_mono finds a new alias name in one of its directives, it will assign all the parameters for that alias to a new mod-mono-server instance.

As you can see there are two differences, apart from some lines shuffled. One is that AddMonoApplications in line 9 changed its first argument to be 'personal'. The other is line 12, that introduces MonoSetServerAlias . This directive tells mod_mono which instance of mod-mono-server will be used to process the requests for this . It can be used with apache too. Inside we didn't need to use MonoSetServerAlias as the absence of this directive means that we want the 'default' instance to be used.

Control panel

mod_mono provides a simple web-based control panel for restarting the mod-mono-server, which is useful when assemblies need to be reloaded from disk after they have been changed. To activate the control panel, place the following in your httpd.conf:

  SetHandler mono-ctrl
  Order deny,allow
  Deny from all
  Allow from 127.0.0.1

The control panel is then accessible at http://yourdomain.com/mono . Clicking the link to restart mod-mono-server will immediately restart it.

The Order/Deny/Allow access controls above restrict access to the control panel to the computer with IP address 127.0.0.1. Replace this (or add more Allow lines) with the IP address of your own computer so that you can access the control panel.

Advanced options

Setting memory and time limits

You know how to make mod_mono start one or more mod-mono-server instances. Here's an example on how to set memory and CPU limits for a given server:

1   LoadModule mono_module modules/mod_mono.so
2   Alias /jeanette "/home/jeanette/web"
3   AddMonoApplications jeanette "/jeanette:/home/jeanette/web"
4   MonoMaxMemory jeanette 200000000
5   MonoMaxCPUTime jeanette 3600
6   
7       MonoSetServerAlias jeanette
8       SetHandler mono
9   

Lines 4 and 5 set the maximum memory to be used (bytes) and the maximum CPU time consumed (seconds) by the 'jeanette' mod-mono-server instance. After reaching the limit, the OS will kill mod-mono-server. You have to take care of starting a new one when it's killed.

Unix and TCP sockets

We said that mod_mono and mod-mono-server can use a unix or a TCP socket to sent data back and forth. Use of unix sockets is the default, but you can use a TCP socket in case you have several computers running apache and one single machine providing mod-mono-server services.

The only parameter that you can control when using a unix socket is the file name. The directive is MonoUnixSocket :

    LoadModule mono_module modules/mod_mono.so

    Alias /julia "/home/julia/web"
    AddMonoApplications default "/julia:/home/julia/web"
    # When no MonoUnixSocket is provided, the default
    # is /tmp/mod_mono_server[_alias]
    # In this case, for the 'default' alias: /tmp/mod_mono_server
    
        SetHandler mono
    

    Alias /jennie "/home/jennie/web"
    AddMonoApplications jennie "/jennie:/home/jennie/web"
    # In this case, alias 'jennie': /tmp/mod_mono_server_jennie
    
        MonoSetServerAlias jennie
        SetHandler mono
    

    Alias /juno "/home/juno/web"
    AddMonoApplications juno "/juno:/home/juno/web"
    # Uses a file under juno's home directory
-   MonoUnixSocket juno /home/juno/tmp/juno_server
    
        MonoSetServerAlias juno
        SetHandler mono
    

You can set the file name to whatever you want as long as the user running apache has the necessary permissions to create and remove that file.

In order to run an instance of mod-mono-server that listens on a TCP socket, there's a mandatory MonoListenPort directive and an optional MonoListenAddress . See them in action:

    LoadModule mono_module modules/mod_mono.so

    Alias /jazmin "/home/jazmin/web"
    AddMonoApplications jazmin "/jazmin:/home/jazmin/web"
    # 'jazmin' mod-mono-server will be listening on
    # port 9000, address 127.0.0.1
-   MonoListenPort jazmin 9000
    
        MonoSetServerAlias jazmin
        SetHandler mono
    

    Alias /joan "/home/joan/web"
    AddMonoApplications joan "/joan:/home/joan/web"
    # 'joan' mod-mono-server will be listening on
    # port 7000, any address (0.0.0.0)
-   MonoListenPort joan 7000
-   MonoListenAddress joan 0.0.0.0
    
        MonoSetServerAlias joan
        SetHandler mono
    

MonoUnixSocket and MonoListenPort are mutually exclusive. Don't use both.

Paths

In case it is needed, you can provide alternative locations for mono executable and mod-mono-server.exe. Other directories containing assemblies that mono could not find in the default search paths can also be specified. Mono needs a writable directory used by the windows I/O emulation layer that is usually in the user's home .wapi directory ($HOME/.wapi). In mod_mono, the directory where .wapi is created is set to /tmp, but you can change that too.

    LoadModule mono_module modules/mod_mono.so

    Alias /jane "/home/jane/web"
    AddMonoApplications jane "/jane:/home/jane/web"

    #
    # Before mod_mono 1.1.17
    #
    # This uses mono 1.1.4 and ASP.NET 1.1 mod-mono-server
    MonoExecutablePath jane /nfs/mono-1.1.4/bin/mono
    MonoServerPath jane /nfs/mono-1.1.4/lib/mono/1.0/mod-mono-server.exe

    #
    # Since mod_mono 1.1.17
    #
    MonoServerPath jane /nfs/mono-1.1.17/mod-mono-server

    
        MonoSetServerAlias jane
        SetHandler mono
    

    Alias /jackie "/home/jackie/web"
    AddMonoApplications jackie "/jane:/home/jackie/web"

    # This uses mono from SVN and the alpha ASP.NET 2.0 mod-mono-server

    #
    # Before mod_mono 1.1.17
    #

    MonoExecutablePath jackie /svn/install/bin/mono
    MonoServerPath jackie /svn/install/lib/mono/2.0/mod-mono-server2.exe
    #
    # Since mod_mono 1.1.17
    #
    MonoServerPath jackie /svn/install/lib/mod-mono-server2

    #
    # Add this directories to the default paths searched by mono
    # when looking for assemlies
    MonoPath jackie "/home/jackie/NET/assemblies:/usr/local/assemblies"
    # The .wapi directory will be created in /home/jackie
    MonoWapidir jackie "/home/jackie"
    
        MonoSetServerAlias jackie
        SetHandler mono
    

Troubleshooting

Access forbidden

If you're getting a 403 response from apache that probably means that the user running apache does not have proper permissions to read the physical directory. Check the permissions on all the directories and the files and make then readable by the user running apache.

mod-mono-server does not start

Check the apache error_log file (/var/log/apache2/error_log ...). It might contain some hints on what's happening. Possible causes are that mono or mod-mono-server are not found in the path, that a file with the same name as the unix socket mod-mono-server tries to create already exists and mod-mono-server can't remove it or a stale .wapi directory.

Restarting apache does not kill the spawned mod-mono-server.exe(s)

Use 'apachectl reload' instead of 'apachectl restart'. There is some problem (may be fixed in apache 2.0.54) that made 'restart' not work properly.

Problems with mod_mono and cookie-less sessions

For cookie-less sessions to work, you need to use SetHandler . AddHandler won't work.

Automatic Hosting of Applications

This has moved to the AutoHosting document.

mod_mono on Windows

For a Windows port of mod_mono, see here  (http://dev.anmar.eu.org/mono/mod_mono/ ) . This is a work in progress.

Profiling mod-mono-server

If you want to find the bottleneck in you ASP.NET application using mod_mono, and assuing you're letting mod_mono start mod-mono-server, you'll need to follow these steps:

1. Start apache.
2. Run 'ps aux' and copy the command line used to run mod-mono-server.exe
3. Stop apache
4. With the same user that runs apache, run the command line copied in 2 adding the '--profile' parameter to mono.
5. Start apache.
6. Do a few requests (they will take a lot to process).
7. Stop apache
8. mod-mono-server will stop and you'll get profile output.

Note that when --profile is enabled, mono is *extremely* slow. Do as many request as you need to get a result that excludes start up stuff.

Compiling mod_mono From Source

If you already have installed mod_mono as a package, skip this section.

Before compiling mod_mono, you need the development packages for apache installed (apache-dev...). You should have a file called mod_mono-X.Y.Z.tar.gz at this stage. Follow these steps:

    $ tar xzf mod_mono-X.Y.Z.tar.gz
    $ cd
 mod_mono-X.Y.Z
(
1
)
 $ ./configure
    $ make
(
2
)
 $ sudo make install

There are a few interesting options for (1) that you might want/need to use:

--prefix= /xxx/yyy 

This will set the base path for installing mod_mono files.

--with-mono-prefix= /aaa/bbb 

If the prefix for mod_mono is different from the one used for mono, you should set this to the prefix used for mono in order to make the default paths to mono executable and mod-mono-server.exe be correct. It is not mandatory, but useful.

--with-apxs= /xxx/yyy/apxs 

If your system has different apache development files installed (ie, 1.3, 2.0 or 2.2) you might need this to choose the target version for mod_mono. Provide the full path to the apxs executable of the version that you want.

--with-apr-config= /xxx/yyy 

If you get errors when compiling for apache 2 because some headers files are not found, use this option. It takes the full path to apache 2 apr-config tool.

--enable-debug 

You will get more output in the apache error_log file. Useful when debugging.