Setting Up And Using Web Services in OS X Mountain Lion Server

Configuring web services is as easy in OS X Mountain Lion Server (10.8) as it has ever been. To set up the default web portal, simply open the Server app, click on the Websites service and click on the ON button.

After a time, the service will start. Once running, click on the View Server Website link at the bottom of the pane.

Provided the stock OS X Server page loads, you are ready to use OS X Server as a web server.

Before we setup custom sites, there are a few things you should know. The first is, the server is no longer really designed to remove the default website. So if you remove the site, your server will exhibit inconsistent behavior. Also, don’t remove the files that comprise the default site. Instead just add sites, which is covered next. Webmail is gone. You don’t have to spend a ton of time looking for it as it isn’t there. Also, Mountain Lion Server adds web apps, which we’ll briefly review later in this article as well.  Finally, enabling PHP and Python on sites is done globally, so this setting applies to all sites hosted on the server.

Now that we’ve got that out of the way, let’s add our first custom site. Do so by clicking on the plus sign. At the New Web Site pane, you’ll be prompted for a number of options. The most important is the name of the site, with other options including the following:

  • Domain Name: The name the site is accessible from. The default sites do not have this option as they are accessible from all names that resolve to the server.
  • IP Address: The IP address the site listens on. Any means the site is available from every IP address the server is configured to use. The default websites do not have this option as they are accessible from all addresses automatically
  • Port: By default, sites without SSL run on port 80 on all network interfaces, and sites with SSL run on port 443 on all network interfaces. Use the Port field to use custom ports (e.g., 8080). The default sites do not have this option as they are configured to use 80 and 443 for default and SSL-based communications respectively.
  • SSL Certificate: Loads a list of SSL certificates installed using Keychain or the SSL Certificate option in the Settings pane of the Server application
  • Store Site Files In: The directory that the files that comprise the website are stored in. These can be placed into the correct directory using file shares or copying using the Finder. Click on the drop-down menu and then select Other to browse to the directory files are stored in.
  • Who Can Access: By default Anyone (all users, including unauthenticated guests) can access the contents of sites. Clicking on Anyone and then Customize… brings up the “Restrict access to the following folders to a chosen group” screen, where you can choose web directories and then define groups of users who can access the contents.
  • Additional Domains: Click on the Edit… button to bring up a simple list of domain names the the site also responds for (e.g. in addition to krypted.com, add www.krypted.com).
  • Redirects: Click on the Edit… button to bring up a list of redirects within the site. This allows configuring redirects to other sites. For example, use /en to load english.krypted.com or /cn to load china.krypted.com).
  • Aliases: Click on the Edit… button to load a list of aliases. This allows configuring redirects to folders within the same server. For example, /en loads /Library/Server/Web/Data/Sites/Default
  • Index Files: Click on the Edit… button to bring up a list of pages that are loaded when a page isn’t directly indicated. For example, when visiting krypted.com, load the wp.php page by default.
  • Advanced Options: The remaining options are available by clicking on the “Edit Advanced Settings…” button.
  • Enable Server Side Includes: Allows administrators to configure leveraging includes in web files, so that pieces of code can be used across multiple pages in sites.
  • Allow overrides using .htaccess files: Using a .htaccess file allows administrators to define who is able to access a given directory, defining custom user names and passwords in the hidden .htaccess file. These aren’t usually required in an OS X Server web environment as local and directory-based accounts can be used for such operations. This setting enables using custom .htaccess files instead of relying on Apple’s stock web permissions.
  • Allow folder listing: Enables folder listings on directories of a site that don’t have an Index File (described in the non-Advanced settings earlier).
  • Allow CGI execution: Enables CGI scripts for the domain being configured.
  • Use custom error page: Allows administrators to define custom error pages, such as those annoying 404 error pages that load when a page can’t be found
  • Make these web apps available on this website: A somewhat advanced setting, loads items into the webapps array, which can be viewed using the following command:  sudo serveradmin settings web:definedWebApps

Once you’ve configured all the appropriate options, click on Done to save your changes. The site should then load. Sites are then listed in the list of Websites.

The Apache service is most easily managed from the Server app, but there are too many options in Apache to really be able to put into a holistic graphical interface. The easiest way to manage the Websites service in OS X Mountain Lion server is using the serveradmin command. Apache administrators from other platforms will be tempted to use the apachectl command to restart the Websites service. Instead, use the serveradmin command to do so. To start the service:

sudo serveradmin start web

To stop the service(s):

sudo serveradmin stop web

And to see the status:

sudo serveradmin fullstatus web

Fullstatus returns the following information:

web:health = _empty_dictionary
web:readWriteSettingsVersion = 1
web:apacheVersion = "2.2"
web:servicePortsRestrictionInfo = _empty_array
web:startedTime = "2012-08-13 23:01:42 +0000"
web:apacheState = "RUNNING"
web:statusMessage = ""
web:ApacheMode = 2
web:servicePortsAreRestricted = "NO"
web:state = "RUNNING"
web:setStateVersion = 1

While the health option typically resembles kiosk computers in the Computer Science departments of most major universities, much of the rest of the output can be pretty helpful including the Apache version, whether the service is running, any restrictions on ports and the date/time stamp that the service was started.

To see all of the settings available to the serveradmin command, run it, followed by settings and then web, to indicate the Websites service:

sudo serveradmin settings web

The output is pretty verbose and can be considered in two sections, the first includes global settings across sites as well as the information for the default sites that should not be deleted:

web:defaultSite:documentRoot = "/Library/Server/Web/Data/Sites/Default"
web:defaultSite:serverName = ""
web:defaultSite:realms = _empty_dictionary
web:defaultSite:redirects = _empty_array
web:defaultSite:enableServerSideIncludes = no
web:defaultSite:customLogPath = ""/var/log/apache2/access_log""
web:defaultSite:webApps = _empty_array
web:defaultSite:sslCertificateIdentifier = ""
web:defaultSite:fullSiteRedirectToOtherSite = ""
web:defaultSite:allowFolderListing = no
web:defaultSite:serverAliases = _empty_array
web:defaultSite:errorLogPath = ""/var/log/apache2/error_log""
web:defaultSite:fileName = "/Library/Server/Web/Config/apache2/sites/0000_any_80_.conf"
web:defaultSite:aliases = _empty_array
web:defaultSite:directoryIndexes:_array_index:0 = "index.html"
web:defaultSite:directoryIndexes:_array_index:1 = "index.php"
web:defaultSite:directoryIndexes:_array_index:2 = "/wiki/"
web:defaultSite:directoryIndexes:_array_index:3 = "default.html"
web:defaultSite:allowAllOverrides = no
web:defaultSite:identifier = "37502141"
web:defaultSite:port = 80
web:defaultSite:allowCGIExecution = no
web:defaultSite:serverAddress = "*"
web:defaultSite:requiresSSL = no
web:defaultSite:proxies = _empty_dictionary
web:defaultSite:errorDocuments = _empty_dictionary
web:defaultSecureSite:documentRoot = "/Library/Server/Web/Data/Sites/Default"
web:defaultSecureSite:serverName = ""
web:defaultSecureSite:realms = _empty_dictionary
web:defaultSecureSite:redirects = _empty_array
web:defaultSecureSite:enableServerSideIncludes = no
web:defaultSecureSite:customLogPath = ""/var/log/apache2/access_log""
web:defaultSecureSite:webApps = _empty_array
web:defaultSecureSite:sslCertificateIdentifier = "com.apple.systemdefault.9912650B09DE94ED160146A3996A45EB3E39275B"
web:defaultSecureSite:fullSiteRedirectToOtherSite = ""
web:defaultSecureSite:allowFolderListing = no
web:defaultSecureSite:serverAliases = _empty_array
web:defaultSecureSite:errorLogPath = ""/var/log/apache2/error_log""
web:defaultSecureSite:fileName = "/Library/Server/Web/Config/apache2/sites/0000_any_443_.conf"
web:defaultSecureSite:aliases = _empty_array
web:defaultSecureSite:directoryIndexes:_array_index:0 = "index.html"
web:defaultSecureSite:directoryIndexes:_array_index:1 = "index.php"
web:defaultSecureSite:directoryIndexes:_array_index:2 = "/wiki/"
web:defaultSecureSite:directoryIndexes:_array_index:3 = "default.html"
web:defaultSecureSite:allowAllOverrides = no
web:defaultSecureSite:identifier = "37502140"
web:defaultSecureSite:port = 443
web:defaultSecureSite:allowCGIExecution = no
web:defaultSecureSite:serverAddress = "*"
web:defaultSecureSite:requiresSSL = yes
web:defaultSecureSite:proxies = _empty_dictionary
web:defaultSecureSite:errorDocuments = _empty_dictionary
web:dataLocation = "/Library/Server/Web/Data"
web:mainHost:keepAliveTimeout = 15.000000
web:mainHost:maxClients = "50%"

The second section is per-site settings, with an array entry for each site:

web:customSites:_array_index:0:documentRoot = "/Library/Server/Web/Data/Sites/www2.krypted.com"
web:customSites:_array_index:0:serverName = "www2.krypted.com"
web:customSites:_array_index:0:realms = _empty_dictionary
web:customSites:_array_index:0:redirects = _empty_array
web:customSites:_array_index:0:enableServerSideIncludes = no
web:customSites:_array_index:0:customLogPath = "/var/log/apache2/access_log"
web:customSites:_array_index:0:webApps = _empty_array
web:customSites:_array_index:0:sslCertificateIdentifier = ""
web:customSites:_array_index:0:fullSiteRedirectToOtherSite = ""
web:customSites:_array_index:0:allowFolderListing = no
web:customSites:_array_index:0:serverAliases = _empty_array
web:customSites:_array_index:0:errorLogPath = "/var/log/apache2/error_log"
web:customSites:_array_index:0:fileName = "/Library/Server/Web/Config/apache2/sites/0000_any_80_www2.krypted.com.conf"
web:customSites:_array_index:0:aliases = _empty_array
web:customSites:_array_index:0:directoryIndexes:_array_index:0 = "index.html"
web:customSites:_array_index:0:directoryIndexes:_array_index:1 = "index.php"
web:customSites:_array_index:0:directoryIndexes:_array_index:2 = "/wiki/"
web:customSites:_array_index:0:directoryIndexes:_array_index:3 = "default.html"
web:customSites:_array_index:0:allowAllOverrides = no
web:customSites:_array_index:0:identifier = "41179886"
web:customSites:_array_index:0:port = 80
web:customSites:_array_index:0:allowCGIExecution = no
web:customSites:_array_index:0:serverAddress = "*"
web:customSites:_array_index:0:requiresSSL = no
web:customSites:_array_index:0:proxies = _empty_dictionary
web:customSites:_array_index:0:errorDocuments = _empty_dictionary

The final section (the largest by far) includes array entries for each defined web app. The following shows the entry for a Hello World Python app:

web:definedWebApps:_array_index:15:requiredWebAppNames = _empty_array
web:definedWebApps:_array_index:15:includeFiles:_array_index:0 = "/Library/Server/Web/Config/apache2/httpd_wsgi.conf"
web:definedWebApps:_array_index:15:requiredModuleNames:_array_index:0 = "wsgi_module"
web:definedWebApps:_array_index:15:startCommand = ""
web:definedWebApps:_array_index:15:sslPolicy = 0
web:definedWebApps:_array_index:15:requiresSSL = no
web:definedWebApps:_array_index:15:requiredByWebAppNames = _empty_array
web:definedWebApps:_array_index:15:launchKeys = _empty_array
web:definedWebApps:_array_index:15:proxies = _empty_dictionary
web:definedWebApps:_array_index:15:preflightCommand = ""
web:definedWebApps:_array_index:15:stopCommand = ""
web:definedWebApps:_array_index:15:name = "com.apple.webapp.wsgi"
web:definedWebApps:_array_index:15:displayName = "Python "Hello World" app at /wsgi"

Each site has its own configuration file defined in the array for each section. By default these are stored in the /Library/Server/Web/Config/apache2/sites directory, with /Library/Server/Web/Config/apache2/sites/0000_any_80_www2.krypted.com.conf being the file for the custom site we created previously. As you can see, many of the options available in the Server app are also available in these files:

<VirtualHost *:80>
ServerName www2.krypted.com
ServerAdmin admin@example.com
DocumentRoot "/Library/Server/Web/Data/Sites/www2.krypted.com"
DirectoryIndex index.html index.php /wiki/ default.html
CustomLog /var/log/apache2/access_log combinedvhost
ErrorLog /var/log/apache2/error_log

<IfModule mod_ssl.c>
SSLEngine Off
SSLCipherSuite "ALL:!aNULL:!ADH:!eNULL:!LOW:!EXP:RC4+RSA:+HIGH:+MEDIUM"
SSLProtocol -ALL +SSLv3 +TLSv1
SSLProxyEngine On
SSLProxyProtocol -ALL +SSLv3 +TLSv1
</IfModule>

<Directory "/Library/Server/Web/Data/Sites/www2.krypted.com">
Options All -Indexes -ExecCGI -Includes +MultiViews
AllowOverride None
<IfModule mod_dav.c>
DAV Off
</IfModule>
<IfDefine !WEBSERVICE_ON>
Deny from all
ErrorDocument 403 /customerror/websitesoff403.html
</IfDefine>
</Directory>

</VirtualHost>

The serveradmin command can also be used to run commands. For example, to reset the service to factory defaults, delete the configuration files for each site and then run the following command:

sudo serveradmin command web:command=restoreFactorySettings

The final tip I’m going to give in this article is when to make changes with each app. I strongly recommend making all of your changes in the Server app when possible. When it isn’t, use serveradmin and when you can’t make changes in serveradmin, only then alter the configuration files that come with the operating system by default. I also recommend keeping backups of all configuration files that are altered and a log of what was altered in each, in order to help piece the server back together should it become unconfigured miraculously when a softwareupdate -all is run next.

  • RK

    You’re articles are very informative and I very much appreciate the work you’ve put into them. Thank you.

    Would you consider writing an article on setting up Apache caching in ML?

    –RK

    • http://www.krypted.com Charles

      I will do so as soon as I get a moment. Love requests! :)

  • Jamie

    Hey,

    First of all, thanks for doing this – as a new OSX server user i was more than a little confused. I have one question – You mentioned under the site configuration descriptions that you can change “Who Can Access” by:

    “Clicking on Anyone and then Customize… brings up the “Restrict access to the following folders to a chosen group” screen, where you can choose web directories and then define groups of users who can access the contents.”

    I don’t seem to be able to work out where “Customize” is… I have set up a new user called “webuser” whom I want to give access to…

    Thanks again!

    Jamie

    • http://www.krypted.com Charles

      Is this the default site?

  • Luis Rojas

    Hi,

    Just found your blog and i think is an amazing resource, i have another suggestion that, hopefully, you will have some answers to.

    It used to be that it was relatively easy to set up a subversion server and offer it under apache+webdav, apple even had an article on how to set it up in snow leopard server. That article, it seems, is gone and our svn repositories are going to break in Mountain Lion Server. Do you have any idea how to fix this?

    Thanks in advance,

    • http://www.krypted.com Charles

      I’ll do an updated write up of it asap

  • Usman

    Since the default server website can no longer be de-activated, how can I run a different website on the same ports (80, 443)?

    Thanks so much for your help and for the very informative article!

    • http://www.krypted.com Charles

      It automatically routes traffic based on the name you supply each site. So just add another, provide the name and it should work. Good luck.

  • Gerry

    Hi Charles, you mentioned you enjoyed a challenge…!

    I’m trying to do something under OS X server which is relatively painless to do on any Linux server, but the undocumented internals of OS X are stymying me.

    My ML 10.8.1 Server is serving three FQDN’s for mail and websites -FQDN 1- ML wiki / device manager / webcal, FQDN 2- one cms + a crm in a subdomain and FQDN 3, a plain HTML info site.

    I have another internal machine / site that does snmp monitoring of the machines on the LAN as well as ups monitoring via NUT ( driver for the ups will not work under OS X either integrated Energy Settings Panel or under NUT USB driver.)

    I’d like to be able to access the snmp HTML server externally. It’s a trivial exercise to set a different port on the router and direct that to the snmp machine, or, if my main webserver was running Linux, to redirect via apache reverse proxy, but unfathomable in Mountain Lion apache setup via webapp.

    I’ve tried unsuccessfully to create a webapp plist to perform the proxy redirect to another internal LAN IP address:80 but it keeps breaking web sites within Server App.

    I know you have a lot of free time :) so if you can maybe do an article on reverse proxy via webapp to another machine I’d be very happy!

    Keep up the great work

  • alex

    thanks Charles

    I am sorry . No speak english.
    I have several domains registered [goddady registered ]
    I need to host these domains on my server. [ your tutorial is OK ]
    but…
    I have only one computer.
    I have only one internet connection.
    I need to access each of these domains separately to install drupal and then, edit their Web-page content… but only can access to Apple default site !!!

    What should I do to access each of my custom pages from the server itself Mountain Lion Server?
    One more time , I am sorry for my english .

    • http://www.krypted.com Charles

      No worries about the English thing. When the sites aren’t loading like that it’s probably a DNS thing. As a temporary fix just until you get the site ready to cut DNS over, you can edit the /etc/hosts file of a client to be able to see each correct site. To install Drupal in multiple instances though, you’ll likely need to do some manual work to connect each sites copy of Drupal to a centralized MySQL database…

  • Alex

    Thanks Charles.

    I understand I can not access these domains locally from the same machine that contains the Mountain Lion Server?
    Can I edit the websites from a laptop inside this network conexion ?

    If yes…

    What should I write in the address bar of the browser to access each site and to edit?

    Other solution…

    I can give to each domain name that I add ….” a different port” , for example:

    Apple default: 80
    Adomain.com: 81
    Adomain.com: 82
    Adomain.com: 83

    I then, also must open each of these ports on the router ?

    lot of love Charles

    Alex

  • alex

    Thanks Charles.
    If edit /etc/hosts file like this : [127.0.0.1 http://www.myweb0x.com ….NO working !!!! ]

    ##
    # Host Database
    #
    # localhost is used to configure the loopback interface
    # when the system is booting. Do not change this entry.
    ##
    127.0.0.1 localhost
    255.255.255.255 broadcasthost
    ::1 localhost
    fe80::1%lo0 localhost
    127.0.0.1 http://www.myweb01.com
    127.0.0.1 http://www.myweb02.com
    127.0.0.1 http://www.myweb03.com
    127.0.0.1 http://www.myweb04.com

    but…like this [192.168.1.100 http://www.myweb0x.com ….NO working !!!! ] ……YES !!!!
    [ 192.168.1.100 is the server internal IP.]

    ##
    # Host Database
    #
    # localhost is used to configure the loopback interface
    # when the system is booting. Do not change this entry.
    ##
    127.0.0.1 localhost
    255.255.255.255 broadcasthost
    ::1 localhost
    fe80::1%lo0 localhost
    192.168.1.100 http://www.myweb01.com
    192.168.1.100 http://www.myweb02.com
    192.168.1.100 http://www.myweb03.com
    192.168.1.100 http://www.myweb04.com

    Es ok ?

    Thanks

    • http://www.krypted.com Charles

      Looks fine, although I normally put my custom entries at the top of the file and I normally don’t test accessibility from the localhost but instead from a separate machine. Hope that helps.