====== How to use Hiawatha as a reverse proxy server for Synchronet ======
Synchronet 3.16c and prior versions do not support SSL connections. Synchronet CVS subsequent to 3.16c have an implementation of SSL, but you may either have problems with it working correctly or you may simply wish to use Hiawatha's implementation of SSL. Hiawatha also has several other security features which can be useful for increasing security for Synchronet's webserver.

====== Installation of Hiawatha ======

Hiawatha is available for Windows, Mac OSX, and many different Linux distributions. Check your operating system's package repositories or visit Hiawatha's download page at https://www.hiawatha-webserver.org/download

General setup of Hiawatha is beyond the scope of this tutorial, but you will find some helpful information at the following pages.

https://www.hiawatha-webserver.org/support
https://wiki.archlinux.org/index.php/Hiawatha

====== Minimal Hiawatha Configuration to use as a reverse proxy server ======

The default location for the Hiawatha configuration file may differ on your system, but for our example we will refer to /etc/hiawatha/hiawatha.conf.

open /etc/hiawatha/hiawatha.conf as root and scroll toward the bottom of the file. You'll see a commented out example section with the heading "VIRTUAL HOSTS". Create a section similar to the one below.

<code>
VirtualHost {
        Hostname = stardate.synchro.net
        WebsiteRoot = /home/sbbs/sbbs/web/root
        StartFile = index.ssjs
        ReverseProxy .* http://127.0.0.1:81/
        RequireTLS = yes
}
</code>

1. Hostname: Assume your BBS's name is The Star Date BBS, and your URL is stardate.synchro.net. You'll place this on the first line.
2. WebsiteRoot: The next line is the root directory of Synchronet's webserver. Change this to /sbbs/web/root, /opt/sbbs/web/root or whatever the location is on your system.
3. StartFile: This is the name of the default page to load when someone accesses your web page.
4. ReverseProxy: This tells Hiawatha to redirect the traffic it receives to this IP address and port. This will be the same IP address and port you will configure your Synchronet webserver to listen to. This could be another IP address such as 192.168.0.100 if this is the Synchronet webserver's IP address. This could be necessary if Hiawatha is running on a different machine that the Synchronet webserver. However, 127.0.0.1 is more secure. If you do have to use the machine's LAN IP address, make sure you're using iptables or some other firewall to ensure that the Synchronet webserver cannot be accessed directly from the internet thus circumventing your proxy server.
5. RequireTLS: This line is completely optional, but you can enable this if you want to force SSL/TLS connections to your website. This requires that an SSL certificate be properly installed and configured with Hiawatha.

====== Synchronet webserver configuration ======

Edit your sbbs.ini file:

Example:
<code>
nano /home/sbbs/sbbs/ctrl/sbbs.ini
</code>

Look for the Web heading:

<code>
[Web]   Web (HTTP) Server
        AutoStart=true
        Interface=127.0.0.1
        Port=81
        TLSInterface=127.0.0.1
        TLSPort=444
</code>

In the default configuration, Interface and TLSInterface are blank. Change the value to match the IP address specified in Hiawatha's ReverseProxy line. Again, if Hiawatha and Synchronet are running on the same machine, the loopback interface (127.0.0.1) is the most secure, but you may need to use the IP address of the machine running the Synchronet web server if they are on different machines.

In the default configuration, the default HTTP port is 80, and the default HTTPS port is 443. In our example, we are setting the default HTTP port to 81 because Hiawatha will be listening on port 80. We want to set Synchronet to listen on a different port. The port number isn't that important, but it should match the port that Hiawatha is proxying traffic to, and it should be a port that no other service is bound to.

In our example, we are setting the HTTPS port for Synchronet's web server to 444 so that it will not conflict with Hiawatha which will be listening for incoming connections on port 443. Alternatively, you could also disable Synchronet web server's binding to an HTTPS port completely since, in this example setup, we will not be making use of that port anyway because Hiawatha will be handling HTTPS and passing it to Synchronet as HTTP.

====== Obtaining a free SSL certificate from Let's Encrypt ======

This section is optional because a sysop may obtain an SSL certificate from any number of certificate authorities. However, Let's Encrypt is an attractive option for sysops who want a free option to quickly and easily add encryption to their website without triggering a security warning in a user's browser as would be the case with a self-signed certificate.

Using Let's Encrypt is fairly simple and straightforward. The official documentation of Let's Encrypt can be found at https://letsencrypt.org/getting-started/ While installation of Let's Encrypt can vary depending on your operating system, many Linux distros offer the client on their repositories. If it isn't available for your distribution, you can use the standalone client available from the Let's Encrypt website.

In our example, we'll assume that your Synchronet installation's webserver root is at /home/sbbs/sbbs/web/root and your web site address is stardate.synchro.net. Ensure that Synchronet's web server is running so that Let's Encrypt can access the server and verify that you control the site you are registering. Then, as root, you would enter

<code>
letsencrypt certonly --webroot -w /home/sbbs/sbbs/web/root -d stardate.synchro.net
</code>

Let's Encrypt will install its data in /etc/letsencrypt by default.

====== Installing the Let's Encrypt SSL certificate into Hiawatha ======

Once you've obtained a Let's Encrypt SSL certificate, run the following command as root, assuming that the URL you registered is stardate.synchro.net

<code>
cat /etc/letsencrypt/live/stardate.synchro.net/privkey.pem /etc/letsencrypt/live/stardate.synchro.net/cert.pem /etc/letsencrypt/live/stardate.synchro.net/chain.pem > /etc/hiawatha/stardate.synchro.net.pem
</code>

Then set the correct permissions so that the certificate can only be read by root.

<code>
chmod 400 /etc/hiawatha/stardate.synchro.net.pem
</code>

Edit /etc/hiawatha/hiawatha.conf and look for the heading "BINDING SETTINGS" near the top. Ensure that your settings look similar to the following:

<code>
# BINDING SETTINGS
# A binding is where a client can connect to.
#
Binding {
        Port = 80
#       Interface = 127.0.0.1
#       MaxKeepAlive = 30
#       TimeForRequest = 3,20
}
#
Binding {
        Port = 443
#       Interface = ::1
#       MaxKeepAlive = 30
#       TimeForRequest = 3,20
        TLScertFile = stardate.synchro.net.pem
}
</code>

The name of the TLScertFile could be a complete patch such as /etc/hiawatha/stardate.synchro.net.pem but a full path shouldn't be necessary if the certificate is in the same directory as the Hiawatha configuration file.

Finally start (or restart) the Hiawatha web server.

<code>
/etc/init.d/hiawatha restart
</code>

And, if you haven't already, restart or recycle your Synchronet web server so that the changes made earlier will take effect.

<code>
/etc/init.d/sbbs restart
</code>

Open up your preferred web browser and point it to your web site and test it with http and https prefixes to ensure everything works properly.

<code>
https://stardate.synchro.net
</code>

For more information, you may refer to the following Hiawatha forum post: https://www.hiawatha-webserver.org/forum/topic/2085

====== To Do for Wiki ======
<code>
1. Update Wiki to reflect minor default path changes from Hiawatha 10.0 to 10.1.
2. Possibly update Wiki to support Hiawatha 10.2's built-in support for Let's Encrypt.
3. Add Wiki section on setting up automatic renewal of Let's Encrypt certificates.
</code>
===== See Also =====
  * [[:howto:|howto index]]

{{tag>}}