www/nginx: more docs (#39)

source/manual/how-tos/nginx_hosting.rst

@@ -0,0 +1,144 @@
+============================
+nginx: Local Website Hosting
+============================
+
+.. Warning::
+
+    Even if you can host websites directly from OPNsense, it is not recommended for security reasons - especially when
+    sending requests to a local PHP interpreter. Do NOT consider using the feature to serve PHP content locally in
+    enterprise networks. It is intended for home users who want to save money by saving power and know what they are
+    doing. If you do not know how to handle a web server properly, do not enable this feature.
+    
+Prepare
+=======
+
+First of all, a directory has to be created. For example `/srv/web_application1`. Please note that this directory must be
+accessable by nginx and PHP (both running as `www`).
+
+For example, you can chmod it (+rx for directories, +r for files for this user) or `chown` it.
+
+.. code-block:: sh
+
+    # create a directory
+    mkdir -p /srv/web_application1
+    cd /srv
+    stat web_application1
+    # Example Result:
+    # 86 18009 drwxr-xr-x 2 root wheel 14050 512 "Aug 31 18:28:19 2018" 
+    #  "Aug 31 18:28:19 2018" "Aug 31 18:28:19 2018" "Aug 31 18:28:19 2018"
+    #  32768 8 0 web_application1
+    #
+    # as you can see, everyone can read (r) and switch into the directory (x))
+    #
+    # do this if the directory is not readable or excutable:
+    chmod +rx web_application1
+    
+.. Warning::
+
+    Never use chmod 777 and be careful with write permissions. the most secure way is to
+    change the owner to www (`chown www filename`) and give write permission only to the
+    web server user (`chmod o+w filename`). The same is valid for directories. It would be
+    a good idea not to execute anything in those directories (for example via a special
+    location block in nginx).
+    If you write your own applications, it is recommended to store such data outside of
+    your web root.
+
+When the directory exists, you can create a file in this directory. Let's say, it should be called test.php and should show
+some information about PHP:
+
+
+.. code-block:: sh
+
+    cat > /srv/web_application1/test.php
+    <?php phpinfo();
+
+Press control + d to end the input.
+
+.. Note::
+
+    you can also use vim if you install vim-lite via pkg.
+
+.. code-block:: sh
+
+    # If needed, change the permission to make it readable:
+    chmod +r test.php
+
+.. Note::
+
+    In a real world scenario, you would probably copy an archive (.tar.gz, .tar.xz, .tar.bz or .zip) via SFTP or SCP on the
+    firewall and execute a command to extract it. Read the man pages for tar, the compression tool or unzip for more detailed
+    instructions.
+
+Configure Locations
+===================
+
+.. image:: images/nginx_edit_location_dialog.png
+
+For a location, the following directives are important:
+
+=============================== ======================================================================
+Directive                       Description                                                           
+=============================== ======================================================================
+Match Type and URL Pattern      How to match the location and the pattern                             
+File System Root                directory of web applicaton                                           
+Upstream Servers                Send it to a remote interpreter instead of using the local one        
+Pass Request To PHP Interpreter Check if you want to enable php (runs locally as user www) or remotely
+Router Script                   Sends all request to a specific script (entry point of application)   
+=============================== ======================================================================
+
+
+=============================== ============================
+Directive                       Value
+=============================== ============================
+Match Type and URL Pattern      ~* .*.php or simmilar
+File System Root                /srv/web_application1
+Upstream Servers                empty
+Pass Request To PHP Interpreter checked
+Router Script                   empty
+=============================== ============================
+
+
+Configure HTTP Server
+=====================
+
+.. image:: images/nginx_edit_http_server_dialog.png
+
+Configuring the HTTP server is simple. You need a hostname (for example website.test), a port (8080/TCP is the
+HTTP alternative port, so it is good for testing. For production sites you should stick with the defaults).
+Please select the prevously created location to serve web content. Please also configure a root here,
+because all requests, which do not match, will be handled by the server default. The default server will
+just serve the static file.
+
+
+Testing
+=======
+
+To test if you web server is running, you can paste call it by its IP and port.
+
+.. Note::
+
+    Please note that IPv6 addresses must be enclosed within square brackets like http://[::1]/ or http://[::1]:8080/.
+
+.. code-block:: sh
+
+    curl "http://192.168.0.1:8080/test.php"
+
+
+Security Considerations
+=======================
+
+* This is nginx and not httpd. It will not care about your .htaccess files.
+  Do not put secret data in unprotected directories. You can protect those directories by yourself,
+  but make sure you don't forget them. Some application depend on this file.
+* Do not overlap nor use OPNsense directories as root
+* Do not upload badly maintained software. If your firewall gets compromised,
+  it will become easy to compromise your hosts too.
+* All your applications run under the same user (www)
+* Watch out for advisories_
+* Install updates ASAP
+* Check your logs regularly.
+* Consider hardening your directory and file access permission (like making directories and files read only
+  for nginx and PHP)
+
+.. _advisories: https://nginx.org/en/security_advisories.html
+

source/manual/howtos.rst

@@ -40,6 +40,8 @@ How to's
    how-tos/multiwan
    how-tos/netflow_exporter
    how-tos/nginx
+   how-tos/nginx_hosting
+   how-tos/nginx_waf
    how-tos/openconnect
    how-tos/orange_fr_fttp
    how-tos/pac