diff --git a/getting-started/configure-webserver.rst b/getting-started/configure-webserver.rst index 75c60e6f..ec38650b 100644 --- a/getting-started/configure-webserver.rst +++ b/getting-started/configure-webserver.rst @@ -3,425 +3,338 @@ Configure the Webserver .. include:: /install/includes/hosted-services.rst -You can find current sample configuration files for your webserver within -``contrib/`` of your Zammad installation. -If you're using the package installation, Zammad attempts to automatically -install a configuration file to your Nginx for you. +Configure your webserver to reverse-proxy the Zammad application server. The +page covers obtaining an SSL certificate, adjusting the sample configuration for +Nginx and Apache 2 and reloading the webserver to apply the changes. + +You can find sample configuration files for your webserver within +the ``contrib/`` directory of your Zammad installation. There are +two example files per webserver: ``zammad.conf`` (plain HTTP) and +``zammad_ssl.conf`` (HTTPS). The non-SSL file is intended for +local testing only and must not be used in production. During a +package installation of Zammad, the package automatically copies +the non-SSL ``zammad.conf`` to your webserver's config directory. +For production use, replace it with the ``zammad_ssl.conf`` and +follow the steps on this page. .. note:: - The Zammad installation will not automatically set any host- or server name - for you. + **Docker Compose / Kubernetes users**: - | **Docker Compose / Kubernetes users** - | Please also note the environment information on - :doc:`this page ` + Skip this page. Configure the webserver port, hostname and + scheme via the ``NGINX_*`` and ``ZAMMAD_RAILSSERVER_*`` + variables, as you can find on the + :doc:`environment variables page `. -Get a SSL Certificate (recommended) ------------------------------------ +.. _configure_webserver_obtain_certificate: -Don't know how to get SSL certificates and install them on a webserver yet? -The guide within the tabs below can help you jumping in. +Obtain an SSL Certificate +------------------------- -Make sure to used named configuration. The default sample configuration -for both Nginx and Apache are *not* named. -To fix this, open the ``zammad.conf`` in your webserver's configuration -directory and make sure to replace ``server_name localhost;`` (Nginx) or -``ServerName localhost`` (Apache 2) with Zammad's actual subdomain. +Zammad requires HTTPS in production. Use one of the options below to obtain +a certificate before continuing with the webserver configuration. -**Where?** +Commercial Certificate Authority +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. tabs:: - - .. tab:: Nginx - - .. include:: includes/nginx-config-paths.include.rst - - .. tab:: Apache 2 +Buy an annual certificate from any trusted public CA. A few common options +are `Sectigo`_, `GlobalSign`_ or `DigiCert`_. Install the resulting +certificate, key and chain on your server as you would for any HTTPS +service, then continue with the webserver configuration below. - .. include:: includes/apache-config-paths.include.rst +.. _Sectigo: https://sectigo.com/ssl-certificates-tls +.. _GlobalSign: https://www.globalsign.com/en/managed-ssl +.. _DigiCert: https://www.digicert.com/tls-ssl/ +Let's Encrypt +^^^^^^^^^^^^^ -**How?** +Let's Encrypt issues free, automatically renewable certificates. Two +clients are commonly used. .. tabs:: - .. tab:: I don't need that - - You either already know what you're doing, you're developing or like the - danger. ⚔️ - - .. tab:: Let's Encrypt - - Let's Encrypt is an easy and free way to retrieve valid ssl certificates. - These certificates are valid for 90 days and can be renewed automatically. - - The two most common tools are - `Certbot `_ and - `acme.sh `_. - - .. tabs:: - - .. tab:: Certbot - - If not happened automatically, you have to install - the Nginx or Apache plugin for Certbot: - ``python3-certbot-nginx`` OR ``python3-certbot-apache`` - - During the first Certbot run it will request additional information - once. Replace ```` in below command by either - ``apache``, ``httpd`` or ``nginx`` and to match your setup. - - .. code-block:: console - - $ certbot -- -d zammad.example.com - - Certbot will now attempt to issue a certificate for you. - If successful, Certbot will ask you if you want to - ``[1] not redirect`` or ``[2] redirect`` automatically. - You can choose to not redirect **if** you plan to use the sample - configuration of Zammad. If not, select ``[2] redirect``. - - From this moment on, Certbot will automatically renew your - installed certificates if they're valid for another 30 days or less. - - .. hint:: **Not exactly what you're looking for?** - - The `Certbot documentation`_ - has a lot more use cases than we cover here. - - .. tab:: acme.sh - - .. note:: - - acme.sh by default no longer uses Let's Encrypt. - For this reason you'll have to change the default CA. - - .. code-block:: console - - $ acme.sh --set-default-ca --server letsencrypt - - If you want to use any other CA with acme.sh, consult their - documentation on how to. - - First of all you'll need to issue your certificate. - acme.sh will save this certificate to - ``/root/.acme.sh//`` - - Replace ```` in the following command by either - ``apache`` or ``nginx`` and to match your setup, use ``standalone`` for other webservers. - - .. code-block:: console - - $ acme.sh --issue -- -d zammad.example.com - - It's not recommended to use the just stored certificates directly. - Instead you should install the certificate to a directory of your - choice. - - We're using ``/etc/ssl/private/`` in this case, but you can use any - directory you like. - - .. warning:: - - Ensure to adjust value for ``--reloadcmd`` as this will - ensure that acme.sh reloads your webserver automatically - after getting a renewal. Replace ```` by either - ``apache2``, ``httpd`` or ``nginx`` - - .. code-block:: console - - $ acme.sh --install-cert -d zammad.example.com \ - --cert-file /etc/ssl/private/zammad.example.com.pem \ - --key-file /etc/ssl/private/zammad.example.com.key \ - --fullchain-file /etc/ssl/private/zammad.example.com.full.pem \ - --reloadcmd "systemctl force-reload " - - From this moment on, acme.sh will automatically renew your - installed certificates if they're valid for another 30 days or less. - - .. hint:: - - **Not exactly what you're looking for?** - - The `acme.sh documentation`_ has a lot more use cases than - we cover here. + .. group-tab:: Certbot - .. tab:: public, paid CA + Certbot is the most widely used ACME client. Follow the + upstream + `Certbot installation instructions `_, + select your distribution and the matching webserver plugin in + the selector and complete the install. Once installed, request + a certificate by replacing ```` with ``nginx`` or + ``apache`` and ``zammad.example.com`` with your subdomain: - If you prefer to use certificates from other official CAs than - Let's Encrypt, you can do so as well. Just get your certificate bundle from - the source you prefer and continue with - `Adjusting the webserver configuration`_. - - .. note:: - - **🙋 I'm new to SSL certificates. Where can I get a certificate?** - - The easiest way to get certificates is to buy an annual - subscription through a commercial CA, such as: - - - `Sectigo (formerly Comodo)`_ - - `Secorio`_ - - `GlobalSign`_ - - (Zammad is not affiliated with these CAs in any way.) + .. code-block:: console - .. tab:: self-signed (discouraged) + $ sudo certbot -- -d zammad.example.com - Another way is to use self signed certificates from your own CA. - In general you shouldn't use this option when you have users accessing - Zammad that can't verify your certificates. + Certbot will issue the certificate, ask whether to redirect + HTTP to HTTPS (choose ``[1] not redirect`` if you plan to use + the Zammad sample configuration, which already handles the + redirect, otherwise choose ``[2] redirect``) and arrange + automatic renewal once the certificate has less than 30 days of + validity remaining. - Beside creating own certificates via e.g. XCA or Microsoft CA, you can - also generate a certificate really quick like so: + .. group-tab:: acme.sh - On any system with ``openssl`` installed, you can run below command. - Provide the requested information and ensure to provide the fqdn of - Zammad when being asked for - ``Common Name (e.g. server FQDN or YOUR name)``. + `acme.sh `_ is a + lightweight shell-based ACME client and an alternative to Certbot, + but it no longer uses Let's Encrypt by default. Set the default + CA to Let's Encrypt before issuing a certificate: .. code-block:: console - $ openssl req -newkey rsa:4096 -nodes -x509 -days 1825\ - -keyout key.pem -out certificate.pem + $ acme.sh --set-default-ca --server letsencrypt - Above command creates a certificate that's valid for 5 years. It will - write the certificate and private key to the current directory you're in. - If you want to check your certificate you just created, you can use the - following command. + Issue the certificate by replacing ```` with + ``nginx``, ``apache`` or ``standalone`` and ``zammad.example.com`` + with your subdomain: .. code-block:: console - $ openssl x509 -text -noout -in certificate.pem + $ acme.sh --issue -- -d zammad.example.com - .. hint:: + Install the certificate to a directory of your choice (e.g. + ``/etc/ssl/private/``) and reload the webserver after each + renewal. Replace ```` in the command below + with the matching systemd service name (``nginx``, ``apache2`` + or ``httpd``): - **Not good enough for you?** + .. code-block:: console - If above command is not good enough for you, the - `openSSL documentation`_ is a good place to learn more. + $ acme.sh --install-cert -d zammad.example.com \ + --cert-file /etc/ssl/private/zammad.example.com.pem \ + --key-file /etc/ssl/private/zammad.example.com.key \ + --fullchain-file /etc/ssl/private/zammad.example.com.full.pem \ + --reloadcmd "systemctl force-reload " -.. _Certbot documentation: https://certbot.eff.org/docs/using.html#certbot-commands -.. _acme.sh documentation: https://github.com/acmesh-official/acme.sh/wiki/How-to-issue-a-cert -.. _Sectigo (formerly Comodo): https://sectigo.com/ssl-certificates-tls -.. _Secorio: https://secorio.com/en/productfinder/ -.. _GlobalSign: https://www.globalsign.com/en/managed-ssl -.. _openSSL documentation: https://www.openssl.org/docs/ + See the `acme.sh documentation`_ for further use cases. -Adjusting the Webserver Configuration -------------------------------------- + .. _acme.sh documentation: https://github.com/acmesh-official/acme.sh/wiki/How-to-issue-a-cert -.. warning:: +.. _configure_webserver_adjust: - For a quick start, we're installing a HTTP configuration. - You should **never** use HTTP connections for authentication - instead, we - encourage you to use HTTPS! - - If Zammad scripts automatically installed your webserver configuration file, - ensure to not rename it. Below we'll cover HTTPs for above reason. +Adjust the Webserver Configuration +---------------------------------- .. tabs:: .. tab:: Nginx (default) - Step 1 - Get a current config file - Copy & overwrite the default ``zammad.conf`` by using + Get the sample config into place + Copy the SSL sample configuration to your Nginx config directory: .. code-block:: console - $ cp /opt/zammad/contrib/nginx/zammad_ssl.conf /etc/nginx/sites-available/zammad.conf - - Your Nginx directories may differ, please adjust your commands if - needed. + $ sudo cp /opt/zammad/contrib/nginx/zammad_ssl.conf \ + /etc/nginx/sites-available/zammad.conf - Most common: + Most common Nginx config directories: .. include:: includes/nginx-config-paths.include.rst - Step 2 - Adjust the config file - Adjust the just copied file with a text editor of your choice (e.g. - ``vi`` or ``nano``). + Adjust server name and certificate paths + Adjust the just copied file with a text editor of your + choice (e.g. vi or nano). + Locate both ``server_name`` directives (one in the HTTP + server block on port 80, one in the HTTPS server block on + port 443) and adjust ``example.com`` to the subdomain you + have chosen for your Zammad instance. - Locate any ``server_name`` directive and adjust ``example.com`` to the - subdomain you have chosen for your Zammad instance. + Now you'll need to adjust the path and file names for + your SSL certificates you obtained on the prior steps. + Adjust the following directives to match your setup: - Now you'll need to adjust the path and file names for your ssl - certificates your obtained on the prior steps. Adjust the following - directives to match your setup: - - - ``ssl_certificate`` (your ssl certificate) + - ``ssl_certificate`` (your SSL certificate) - ``ssl_certificate_key`` (the certificates private key) - ``ssl_trusted_certificate`` (the public CA certificate) - .. note:: - - Technically this is not a hard requirement, but recommended! - - .. include:: /getting-started/include-dhparam-webserver.rst + To improve HTTPS security, also configure a Diffie-Hellman + parameter file and point ``ssl_dhparam`` at it: - (Optional) - Adjust HTTPs configuration - .. include:: /getting-started/include-ssl-config-generator-webserver.rst + .. code-block:: console - Step 3 - Save & reload - Reload your Nginx with ``systemctl reload nginx`` to apply your - configuration changes. + $ sudo openssl dhparam -out /etc/ssl/dhparam.pem 4096 - .. tab:: Apache2 + Reload and verify + Verify the configuration: - Step 1 - Ensure required modules are enabled - Zammad requires modules that are not enabled by default. By default - use ``a2enmod`` (**not** CentOS) to do so. + .. code-block:: console - .. tabs:: + $ sudo nginx -t - .. tab:: a2enmod + Reload Nginx: - .. code-block:: console + .. code-block:: console - $ a2enmod proxy proxy_html proxy_http proxy_wstunnel headers ssl + $ sudo systemctl reload nginx - If you want to run Zammad under HTTP/2, you will also need + .. tab:: Apache 2 - .. code-block:: console + Enable the required modules + Zammad requires modules that are not enabled by default. On + Ubuntu, Debian and openSUSE use ``a2enmod``: - $ a2enmod h2 proxy_http2 mpm_event + .. code-block:: console - .. code-block:: console + $ sudo a2enmod proxy proxy_html proxy_http proxy_wstunnel \ + headers ssl - $ sudo systemctl restart apache2 + For HTTP/2 support also enable: - .. tab:: via configuration file (CentOS) + .. code-block:: console - add/uncomment the appropriate ``LoadModule`` statements - in your Apache config: + $ sudo a2enmod h2 proxy_http2 mpm_event - .. code-block:: text + On CentOS / RHEL add the matching ``LoadModule`` lines to + ``/etc/httpd/conf/httpd.conf`` instead: - # /etc/httpd/conf/httpd.conf + .. code-block:: text - LoadModule headers_module modules/mod_headers.so - LoadModule proxy_module modules/mod_proxy.so - LoadModule proxy_html_module modules/mod_proxy_html.so - LoadModule proxy_http_module modules/mod_proxy_http.so - LoadModule proxy_wstunnel_module modules/mod_proxy_wstunnel.so + LoadModule headers_module modules/mod_headers.so + LoadModule proxy_module modules/mod_proxy.so + LoadModule proxy_html_module modules/mod_proxy_html.so + LoadModule proxy_http_module modules/mod_proxy_http.so + LoadModule proxy_wstunnel_module modules/mod_proxy_wstunnel.so - Don't forget to restart your Apache. + Restart Apache after enabling the modules: - Step 2 - Get a current config file - .. note:: + .. code-block:: console - Package installations attempt to copy a ``zammad.conf`` to your - webserver's configuration directory. **Do not rename** this file! + $ sudo systemctl restart apache2 - Copy & overwrite the default ``zammad.conf`` by using + Get the sample config into place + Copy the SSL sample configuration to your Apache config directory: .. code-block:: console - $ cp /opt/zammad/contrib/apache2/zammad_ssl.conf /etc/apache2/sites-available/zammad.conf + $ sudo cp /opt/zammad/contrib/apache2/zammad_ssl.conf \ + /etc/apache2/sites-available/zammad.conf - Your Apache directories may differ, please adjust your commands - if needed. - - Most common: + Most common Apache config directories: .. include:: includes/apache-config-paths.include.rst - Step 3 - Adjust the config file - Adjust the just copied file with a text editor of your choice (e.g. - ``vi`` or ``nano``). + The package installation attempts to copy this file for you. + Do not rename it. - Locate any ``ServerName`` directive and adjust ``example.com`` to the - subdomain you have chosen for your Zammad instance. + Adjust server name and certificate paths + Adjust the just copied file with a text editor of your + choice (e.g. vi or nano). + Locate any ``ServerName`` directive and adjust ``example.com`` + to the subdomain you have chosen for your Zammad instance. + The first ``ServerName`` (in the HTTP VirtualHost) defaults to + ``example.com`` and the second (in the HTTPS VirtualHost) to + ``localhost``. - Now you'll need to adjust the path and file names for your ssl - certificates your obtained on the prior steps. Adjust the following - directives to match your setup: + Now you'll need to adjust the path and file names for + your SSL certificates you obtained on the prior steps. + Adjust the following directives to match your setup: - - ``SSLCertificateFile`` (your ssl certificate) + - ``SSLCertificateFile`` (your SSL certificate) - ``SSLCertificateKeyFile`` (the certificates private key) - ``SSLCertificateChainFile`` (the public CA certificate) - .. note:: + To improve HTTPS security, also configure a Diffie-Hellman + parameter file and point ``SSLOpenSSLConfCmd DHParameters`` at + it: - Technically this is not a hard requirement, but recommended! + .. code-block:: console - .. include:: /getting-started/include-dhparam-webserver.rst + $ sudo openssl dhparam -out /etc/ssl/dhparam.pem 4096 - (Optional) - Adjust HTTPs configuration - .. include:: /getting-started/include-ssl-config-generator-webserver.rst + Enable the site + On Ubuntu, Debian and openSUSE: - (Optional) - Enable the site - .. hint:: + .. code-block:: console - This step mostly depends on your selected folders and most often - only affects ``sites-available`` folders. + $ sudo a2ensite zammad - .. tabs:: + On CentOS / RHEL: - .. tab:: Ubuntu / Debian / openSUSE + .. code-block:: console - .. code-block:: console + $ sudo ln -s /etc/httpd/sites-available/zammad_ssl.conf \ + /etc/httpd/sites-enabled/ - $ a2ensite zammad + Make sure ``IncludeOptional sites-enabled/*.conf`` is present in + ``/etc/apache2/apache2.conf`` (Ubuntu, Debian, openSUSE) or + ``/etc/httpd/conf/httpd.conf`` (CentOS / RHEL). - .. tab:: CentOS + Reload and verify + Reload Apache and verify the configuration: - .. code-block:: console + .. code-block:: console - $ ln -s /etc/httpd/sites-available/zammad_ssl.conf /etc/httpd/sites-enabled/ + $ sudo systemctl reload apache2 - Also, make sure the following line is present in your Apache - configuration: + .. tab:: Local testing or other proxy servers - .. code-block:: text + Zammad's main application listens on port ``3000`` and the websocket + server on port ``6042``. If you put your own reverse proxy in front of + Zammad, forward both. - IncludeOptional sites-enabled/*.conf + If the default ports conflict with other applications on your host, + see :doc:`/appendix/environment-variables` to change them. - You can find your config file in Ubuntu, Debian & openSUSE - under ``/etc/apache2/apache2.conf`` and for CentOS under - ``/etc/httpd/conf/httpd.conf``. + .. warning:: - Step 4 - Save & reload - Reload your Apache to apply your configuration changes: + Do not expose Zammad directly to the internet. Zammad only + provides plain HTTP and would be reachable without + authentication. - .. code-block:: console +Now visit your configured Zammad domain in a browser. You should reach +the Zammad getting started wizard for new installations (see screenshot below). +If you don't see Zammad's setup wizard or Zammad UI at all, check the +:ref:`Troubleshooting section ` below. - $ sudo systemctl reload apache2 +.. figure:: /images/install/getting-started-wizard.png + :alt: Getting started wizard after installing Zammad + :width: 80% + :align: center - .. tab:: local testing or other proxy servers +.. _configure_webserver_troubleshooting: - Want to test locally first or use a different Proxy we don't support? - The main application (Rails server) is listening on - ``http://127.0.0.1:3000``. +Troubleshooting +--------------- - If you're using a proxy server, also ensure that you proxy the websockets - as well. The websocket server listens on ``ws://127.0.0.1:6042``. +Default Landing Page Instead of Zammad +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - If above ports are used by other applications already, please - have a look at :doc:`/appendix/environment-variables`. +If you reach the webserver's default landing page rather than Zammad, +your ``zammad.conf`` may be overruled by another config file. Check +the vhost directory for ``000-default.conf`` or ``default.conf`` and +disable it. - .. warning:: +DNS Not Resolving +^^^^^^^^^^^^^^^^^ - Do not expose Zammad directly to the internet, as Zammad only provides - HTTP! +If the subdomain does not resolve, double-check the DNS records for +your domain and wait for them to propagate. Replace the ``zammad.example.com`` +in the following command with your configured domain of Zammad and check if +the domain points to the right server: -**If you just installed Zammad, you'll be greeted by our getting started -wizard. 🙌** You now can continue with :doc:`first-steps`. +.. code-block:: console -.. hint:: + $ host zammad.example.com - **You're not seeing Zammad's page but a default landing page of your OS?** +CSRF Token Errors +^^^^^^^^^^^^^^^^^ - Ensure that you did restart your webserver - also check if - ``000-default.conf`` or ``default.conf`` in your vhost directory - possibly overrules your configuration. +If users cannot log in because of CSRF token errors, your webserver +chain may not pass the original connection type to Zammad. Tell the +proxy directly that the connection is HTTPS. - Sometimes this is also a DNS resolving issue. +Nginx + Within your virtual host configuration, locate + ``proxy_set_header X-Forwarded-Proto`` and replace ``$scheme`` + with ``https``. -.. include:: /getting-started/include-csrf-hints.rst +Apache 2 + Within your virtual host configuration, just above the first + ``ProxyPass`` directive, insert: -.. figure:: /images/install/getting-started-wizard.png - :alt: Getting started wizard after installing Zammad - :width: 80% - :align: center + .. code-block:: text + + RequestHeader set X_FORWARDED_PROTO 'https' + RequestHeader set X-Forwarded-Ssl on diff --git a/getting-started/include-csrf-hints.rst b/getting-started/include-csrf-hints.rst deleted file mode 100644 index a4655d46..00000000 --- a/getting-started/include-csrf-hints.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. tip:: - - **Can't login because of CSRF token errors?** - - This usually affects systems with more than one proxy server only. - For this to function you may have to tell your web server directly - which connection type was used. Only use the options described below if you're sure. They may cause security issues. - - The following options expect HTTPS connections which should be your goal. - - Nginx - Within your virtual host configuration, locate both directives - ``proxy_set_header X-Forwarded-Proto`` and replace ``$scheme`` by - ``https``. - - Apache2 - Within your virtual host configuration just above the first - ``ProxyPass`` directive insert: - - .. code-block:: text - - RequestHeader set X_FORWARDED_PROTO 'https' - RequestHeader set X-Forwarded-Ssl on diff --git a/getting-started/include-dhparam-webserver.rst b/getting-started/include-dhparam-webserver.rst deleted file mode 100644 index 85e33b33..00000000 --- a/getting-started/include-dhparam-webserver.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. hint:: - - **🤓 Don't have a dhparam.pem file yet?** - - You can easily adapt below example to generate this file. - It will improve HTTPs security and thus should be used. - - You can find the path by looking at your webserver configuration by - looking for: - - - ``ssl_dhparam`` directive (Nginx) - - ``SSLOpenSSLConfCmd DHParameters`` directive (Apache2) - - .. code-block:: console - - $ openssl dhparam -out /dhparam.pem 4096 diff --git a/getting-started/include-ssl-config-generator-webserver.rst b/getting-started/include-ssl-config-generator-webserver.rst deleted file mode 100644 index 2c9e1787..00000000 --- a/getting-started/include-ssl-config-generator-webserver.rst +++ /dev/null @@ -1,5 +0,0 @@ -Our default configuration aims for a broad support of enduser devices. -This may not fit your needs - Mozilla has a great -`ssl-config generator`_ that should help you to meet your requirements! - -.. _ssl-config generator: https://ssl-config.mozilla.org/