[[PageOutline]]

[wiki:howto <- Back to the HOWTO section]

= About Apache = #about

The Apache HTTP Server, commonly referred to simply as Apache, is the world's most-popular web server.

For information on integrating Apache2-2.4.x with MySQL and PHP, see [wiki:howto/MAMP2.4.x MAMP2.4.x]. (Yet to be written - 10-20-17-whm.)

= Versions = #versions

MacPorts includes the following versions of Apache:

* '''apache2''': Apache HTTP Server v2.4.x. This is the current, recommended port to use, and will install if you simply type:

 '''$ sudo port install apache2'''

Apache2-2.4.x has a different directory layout from apache2, so none of the other ports that use apache2 can use apache2.4-.x without modifications.

This page shows how to install and use the apache2-2.4.x  port on High Siarra (OSX 10.13.x).
These instructions cannot be easily adapted to the other ports.
For information of earlier versions of Apache2 visit see [wiki:howto/Apache2].

== October 2017 - Apache2-2.4.28 ==
In October of 2017 <Macports upgraded Apache 2.2.x  to Apache 2.4.x as the default installation. This involved a significant set of changes as listed in the Notes of the portfile:

Apache2 has been migrated from the 2.2.x to the 2.4.x branch.
    
    The install paths have been changed to no longer violate the MacPorts mtree:
    
    1. The binaries are now under '''''/opt/local/sbin/'''''
       (rather than under /opt/local/apache2/bin/)
    
    2. The configure files are now under '''''/opt/local/etc/apache2/'''''
       (rather than under /opt/local/apache2/conf/)
    
    3. The modules are now under '''''/opt/local/lib/apache2/modules/'''''
       (rather than under /opt/local/apache2/modules/)
    
    4. The web root is now located under '''''/opt/local/www/apache2/html/'''''
       (rather than under /opt/local/apache2/htdocs/)
    
    5. The cgi-bin is now located under '''''/opt/local/www/apache2/cgi-bin/'''''
       (rather than under /opt/local/apache2/cgi-bin/)
    
    6. The logs are now located under '''''opt/local/var/log/apache2/'''''
       (rather than under /opt/local/apache2/logs/)
    
    7. The manual is now located under '''''/opt/local/www/apache2/manual/'''''
       (rather than under /opt/local/apache2/manual/)
    
    8. The manual (man) pages are still at '''''/opt/local/share/apache2/man/'''''
    
    You can move your htdocs and cgi-bin to the new locations, or edit /opt/local/etc/apache2/httpd.conf to point at the old
    locations.


= Step 1: '''Turn off Apple's "Personal Web Sharing"''' = #pws

=== OS X 10.13.x  High Sierra  ===
Beginning with Yosemite (OSX 10.10), OSX no longer has Personal Web Sharing as an option in System Preferences.

However,  the Apache 2 web server (Apache/2.4.27) and PHP 7, ar supplied by Apple as part of the High Sierra  distribution.
It is found at `/etc/apache2`; there is no "GUI" way to turn it on (or off), only via the command line.
It is not turned on, or configured, in a default High Sierra installation.

 '''$ sudo apachectl stop'''

=== OS X Server ===
Launch Server Manager and turn off the web server.

= Step 2: '''Install Apache''' = #apache

 '''$ sudo port install apache2'''

A sample configuration file is provided in '''''/opt/local/etc/apache2/httpd.conf.orig'''''.

The first time you install apache2, this sample configuration file will be copied to `/opt/local/etc/apache2/httpd.conf` for you. 
You can edit this file as desired. 
When you later upgrade apache2 to a newer version, MacPorts will upgrade the sample configuration file but will not modify your `httpd.conf`, so be sure to manually compare your `httpd.conf` with the new sample configuration file and bring over any relevant changes. You should also keep backup copies of your `httpd.conf` in a safe place.

A copy of the original `httpd.conf` file and the and configuration files in the extra directory, are found in `/opt/local/etc/apache2/original` so you can refer to the defaults later.

=  Step 3:  '''Verify your config file''' =
Verify any changes you have made to the config file: /opt/local/etc/apache2/httpd.conf

 '''$ /opt/local/sbin/apachectl -t'''

This will return either "Syntax OK" or a specific line by line error listing. Note that this check is strictly a syntax check. 
Logic is not verified. 

* Refer to the manual on the Apache website '''https://httpd.apache.org/docs/2.4/''' , or the manual installed at  '''/opt/local/www/apache2/manual/'''. 
* Note however that the local manual is in html format, and since the server is not working, you will have a difficult time reading it.

=  Step 4: '''Activate Apache2''' =
Activate your Apache installation so that it starts now and every time you boot your machine: 

 '''$ sudo port load apache2'''

If when you issue this command, you immediately receive the message:

 '''/opt/local/etc/LaunchDaemons/org.macports.apache2/org.macports.apache2.plist: service already loaded'''

This means that the Launch Daemon believes that it has successfully started Apache.  You probably did not shut it down in step 1 above:

 '''$ sudo port unload apache2'''

to stop apache (even though it is not running) and then start it using

 '''$ sudo port load apache2'''

to start it again.

* type 'localhost' in the address bar of Safari, and press enter. You should see '''It Works! ''' displayed in the browser window.

If the web server  is NOT running at this point, a configuration error is your most likely problem. 

Verify your config file as in step 3 above and make any necessary corrections.

After each change to the config file, you should again verify the file syntax, and then you need to stop and restart Apache for the changes to take effect.

 '''$ /opt/local/sbin/apachectl -t'''\\
 '''$ sudo port unload apache2'''\\
 '''$ sudo port load apache2'''

The default log file location is: `/opt/local/var/log/apache2/'` The shutdown and startup attempt will be logged in "'''error_log'''"

* Typical start messages found in "error_log:\\
 [DATE-TIME] [mpm_prefork:notice] [pid nnnn] AH00163: Apache/2.4.27 (Unix) PHP/7.1.7 configured -- resuming normal operations\\
 [DATE-TIME] [core:notice] [pid nnnn] AH00094: Command line: '/usr/sbin/httpd -D FOREGROUND'\\


* Typical shutdown  message found in "error_log:\\
 [Sat Oct 21 14:21:23.781001 2017] [mpm_prefork:notice] [pid 6239] AH00169: caught SIGTERM, shutting down


= Step 5: '''Initial changes to the config file''' =
Once you have determined that your basic installation is working, you need to consider making some initial changes to your config file.

Remember: after each change to the config file, you should again verify the file syntax, and then you need to stop and restart Apache for the changes to take effect.

 '''$ /opt/local/sbin/apachectl -t'''\\
 '''$ sudo port unload apache2'''\\
 '''$ sudo port load apache2'''\\

In Apache documentation, you will see the use of "''apachectl -k restart''" described as the method to cause the config file to be re-read.

However under OSX, the purpose of ''launchd'' is to notice processes that stop without its knowledge, and to restart them. 
So if you use ''apachectl -k restart'', launchd may notice apache "crashing" and restart it itself, confusing apachectl. 
Instead, you shoulduse "port" to tell launchctl to unload apache2, then load it again. 
This will result in a short interruption of service.

If the sever name is not set properly in the configuration file, `/opt/local/etc/apache2/httpd.conf`, you will encounter the warning below. 

 '''''httpd: Could not reliably determine the server's fully qualified domain name, using <Computer-Name>.local for ServerName'''''

Where `<Computer-Name>` refers to the name of your computer as specified in the System Preferences Sharing pane.  To resolve the warning, edit the configuration file and set the server name appropriately.  For personal use, `localhost` is sufficient.

 '''''ServerName localhost:80'''''

To verify Apache is now running, point your browser to http://localhost/ (you may need to reload the page). You should see a page that says '''It works! '''

If desired, reboot your machine and point your browser again to http://localhost/ to confirm that Apache is again running following the system boot.

=== User directories === #userdir

If you would like to be able to access web pages in the 'Sites' directory of your users' home directories, edit `/opt/local/etc/apache2/httpd.conf` and locate the following lines:

{{{
#LoadModule userdir_module lib/apache2/modules/mod_userdir.so
#LoadModule socache_shmcb_module lib/apache2/modules/mod_socache_shmcb.so
#Include conf/extra/httpd-userdir.conf
}}}

Uncomment them by removing the "`#`" at the start of the line so that it reads:

 '''Include conf/extra/httpd-userdir.conf'''\\
 '''LoadModule userdir_module lib/apache2/modules/mod_userdir.so'''\\
 '''LoadModule socache_shmcb_module lib/apache2/modules/mod_socache_shmcb.so'''\\

Then copy the file '''/opt/local/etc/apache2/extras/httpd-userdir.conf.orig''' to '''/opt/local/etc/apache2/extras/httpd-userdir.conf'''

 '''$ cd /opt/local/etc/apache2/extras/'''
 '''$ sudo cp httpd-manual.conf.orig httpd-userdir.conf'''
 '''$ sudo chmod og+r httpd-userdir.conf'''

In its default state, '''httpd-userdir.conf''' permits access to all users '''public_html''' directory.\
To enable a users '''Sites''' directory, change both occurrences of "public_html" to '''Sites'''

This file:   ''"/opt/local/etc/apache2/extra/httpd-userdir.conf"'' will then activate the "Sites" sub-directory for all users on your system. (''"/Users/*/Sites"'') and contains initial, basic restrictions for access to the contents of that directory.

After each change to the config file, you should again verify the file syntax, and then you need to stop and restart Apache for the changes to take effect.

 '''$ /opt/local/sbin/apachectl -t'''\\
 '''$ sudo port unload apache2'''\\
 '''$ sudo port load apache2'''\\

You can then view your personal pages by accessing http://localhost/~username/, where "username" is your Mac OS X account's short name.
 '''Note:''' On a clean install of High Sierra, users will need to create their own Sites directory

=== Local Apache manual === #manual

The [http://httpd.apache.org/docs/2.4/ Apache manual] is available on the Apache web site. \\
If you would like to be able to access a copy of this manual on your web server, edit `/opt/local/etc/apache2/httpd.conf` and uncomment the following line:

{{{
#Include conf/extra/httpd-manual.conf
}}}

So that it reads like this:

 '''Include conf/extra/httpd-manual.conf'''

Then copy the file '''/opt/local/etc/apache2/extras/httpd-manual.conf.orig''' to ''/opt/local/etc/apache2/extras/httpd-manual.conf'' 

 '''$ cd /opt/local/etc/apache2/extras/'''\\
 '''$ sudo cp httpd-manual.conf.orig httpd-manual.conf'''\\
 '''$ sudo chmod og+r httpd-manual.conf'''\\

At this point a syntax check:  
 $ /opt/local/sbin/apachectl -t
will return the error:

 AH00526: Syntax error on line 36 of /opt/local/etc/apache2/extra/httpd-manual.conf:\\
 Invalid command 'LanguagePriority', perhaps misspelled or defined by a module not included in the server configuration\\

This means that "LanguagePriority" is not included in the default config.  Edit `/opt/local/etc/apache2/httpd.conf` and uncomment the following line:

 '''LoadModule negotiation_module lib/apache2/modules/mod_negotiation.so'''

After each change to the config file, you should again verify the file syntax, and then you need to stop and restart Apache for the changes to take effect.

 '''$ /opt/local/sbin/apachectl -t'''\\
 '''$ sudo port unload apache2'''\\
 '''$ sudo port load apache2'''\\

You can then view the manual by accessing http://localhost/manual/.

= ''' Apache SSL/TLS Encryption (aks Secure Sockets  or https)'''  = #ssl
'''Note:''' Establishing Secure Sockets is a fairly extensive process. One should first read the current Apache2 documentation found in the Apache2 manual:
{{{
http://httpd.apache.org/docs/2.4/ssl/
}}}
=== Generate a self-signed certificate ===
The following instructions are to generate a "self-signed" certificate.\\
This is simply a shortcut for testing purposes (a self-signed certificate is not recommended for production!).\\
The complete dialog is listed here for reference. The commands necessary are prefixed as "$ sudo", with comments prefixed with a #.\\

{{{
$ sudo openssl genrsa -des3 -out server.key 2048
# Enter pass phrase for server.key [enter your passphrase, a simple password we will remove soon]

Generating RSA private key, 1024 bit long modulus
.....++++++
................++++++
e is 65537 (0x10001)
Enter pass phrase for server.key:
Verifying - Enter pass phrase for server.key:

$ sudo openssl req -new -key server.key -out server.csr
# 
# [you can accept all the defaults, it does not matter, or customize it to your liking]

Enter pass phrase for server.key:
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:
State or Province Name (full name) [Some-State]:
Locality Name (eg, city) []:
Organization Name (eg, company) [Internet Widgits Pty Ltd]:
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name) []:
Email Address []:

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:


$ sudo openssl x509 -req -days 3650 -in server.csr -signkey server.key -out server.crt
# [will ask for passphrase - the same as you entered in the first step]

Signature ok
subject=/C=US/ST=Pennsylvania/L=Elizabethtown/O=MVE/OU=Elizabethtown/CN=mcgillsociety.org/emailAddress=magill@icloud.com
Getting Private key
Enter pass phrase for server.key:

$ sudo cp server.key server.key.bak
$ sudo openssl rsa -in server.key.bak -out server.key
# [will ask for passphrase - the same as you entered in the first step]

Enter pass phrase for server.key.bak:
writing RSA key

$ sudo cp server.crt /opt/local/etc/apache2/
$ sudo cp server.key /opt/local/etc/apache2/
}}}
'''Note:''' Certificate generation can be accomplished in any directory. If you did so in ''"/opt/local/etc/apache2/"'' the last two copy commands are redundant, and will generate the following  errors respectively:
{{{
cp: /opt/local/etc/apache2/server.crt and server.crt are identical (not copied).
cp: /opt/local/etc/apache2//server.key and server.key are identical (not copied).
}}}

=== Activate SSL ===
Enable (uncomment) the following in {{{/opt/local/etc/apache2/httpd.conf}}}

 '''LoadModule ssl_module modules/mod_ssl.so'''

 # Secure (SSL/TLS) connections\\
 '''Include conf/extra/httpd-ssl.conf'''

Then copy the file '''/opt/local/etc/apache2/extras/httpd-ssl.conf.orig''' to ''/opt/local/etc/apache2/extras/httpd-ssl.conf'' 
{{{
 $ cd /opt/local/etc/apache2/extras/
 $ sudo cp httpd-ssl.conf.orig httpd-ssl.conf
 $ sudo chmod og+r httpd-ssl.conf
}}}

A syntax check at this point will yield:
{{{
/opt/local/sbin/apachectl -t
AH00526: Syntax error on line 92 of /opt/local/etc/apache2/extra/httpd-ssl.conf:
SSLSessionCache: 'shmcb' session cache not supported (known names: ). Maybe you need to load the appropriate socache module (mod_socache_shmcb?).
}}}

Then enable (uncomment) the following in {{{/opt/local/etc/apache2/httpd.conf}}}

 '''LoadModule authn_socache_module lib/apache2/modules/mod_authn_socache.so'''

After each change to the config file, you should again verify the file syntax, and then you need to stop and restart Apache for the changes to take effect.

 '''$ /opt/local/sbin/apachectl -t'''\\
 '''$ sudo port unload apache2'''\\
 '''$ sudo port load apache2'''\\

The most likely error you will receive is:
{{{
Syntax error on line 120 of /opt/local/etc/apache2/extra/httpd-ssl.conf:
SSLCertificateFile: file '/opt/local/etc/apache2/server.crt' does not exist or is empty
}}}
If so, simply revisit the instructions above to create a self-signed certificate.

=== Verify your success ===

type ''"https://<your server address>"'' in Safari. \\
Safari should return the pop-up: "Safari can't verify the identity of the website "<your server address>" \\
At which point you can view the details of your certificate and select your appropriate actions.

=== Configure your "Virtual Host" ===
While you have verified your certificate, you will discover that you have no access to your server - ''"You don't have permission to access.... on this server."''\\
This is because the SSL Virtual Host has not been configured in ''"/opt/local/etc/apache2/extra/httpd-ssl.conf"''

Edit ''"/opt/local/etc/apache2//extra/httpd-ssl.conf"'' and moved down to the section:
{{{
#   General setup for the virtual host
DocumentRoot "/opt/local/www/apache2/html"
ServerName www.mcgillsociety.org:443
ServerAdmin magill@icloud.com
ErrorLog "/opt/local/var/log/apache2/error_log"
TransferLog "/opt/local/var/log/apache2/access_log"
}}}
Configure this section appropriately. \\
Assuming you wish to implement SSL on your entire server, ''DocumentRoot'' and ''ServerName'' should match the values in ''"/opt/local/apache2/conf/httpd.conf"''\\
As there are many optional ways of configuring security on your web server, consult the Apache2 manual for details.
{{{
http://httpd.apache.org/docs/2.4/ssl/
}}}

After each change to the config file, you should again verify the file syntax, and then you need to stop and restart Apache for the changes to take effect.

 '''$ /opt/local/apache2/bin/apachectl -t'''\\
 '''$ sudo port unload apache2'''\\
 '''$ sudo port load apache2'''


[wiki:howto <- Back to the HOWTO section]