diff --git a/admin_docs.rst b/admin_docs.rst index d24518d..8ed95cf 100644 --- a/admin_docs.rst +++ b/admin_docs.rst @@ -3,12 +3,14 @@ Admin Documentation ####################################### .. toctree:: - :maxdepth: 3 + :maxdepth: 2 :glob: - admin_docs/server_management.rst + admin_docs/web.rst + admin_docs/dns.rst + admin_docs/mail.rst + admin_docs/database.rst + admin_docs/cron.rst admin_docs/backups.rst - admin_docs/ssl_certificates.rst - admin_docs/user_management.rst - admin_docs/filemanager.rst - admin_docs/rest_api.rst + admin_docs/settings.rst + admin_docs/api.rst \ No newline at end of file diff --git a/admin_docs/api.rst b/admin_docs/api.rst new file mode 100644 index 0000000..458baf0 --- /dev/null +++ b/admin_docs/api.rst @@ -0,0 +1,106 @@ +################################## +Rest Api +################################## + +The Hestia WEB API is available to perform core functions of the Control Panel. We use it internaly to synchronyze DNS clusters, to integrate WHMCS billing system The API can be used as well to create new user accounts, domains, databases or even to build an alternative web interface. + +This reference provides php code samples demonstrating how you can seamlessly integrate API into your application or script. However you can use other languages to communicate with API. + +.. toctree:: + :maxdepth: 2 + :glob: + + api/rest_api.rst + +************************************************ +Unable to connect to the api +************************************************ + +With the release of 1.4 Hestia has decided it was needed to tighten the security. If you connect from a remote server to the api. You are required to enter the ip address into the white. By default 127.0.0.1 is always allowed. If you need multiple ip addresses separate them with an enter. + +.. image:: ../images/api/api-1.png + :width: 600px + :align: center + :height: 376px + :alt: Api settings + +************************************************ +Can I disable the api +************************************************ + +Disable the api via the settings. The file will be deleted from the server and all connections will get ignored. Please note some functions may not work without the api enabled. + +************************************************ +Return Codes +************************************************ + +.. list-table:: + :header-rows: 1 + + * - VALUE + - NAME + - COMMENT + * - 0 + - OK + - Command has been successfuly performed + * - 1 + - E_ARGS + - Not enough arguments provided + * - 2 + - E_INVALID + - Object or atgument is not valid + * - 3 + - E_NOTEXIST + - Object doesn't exist + * - 4 + - E_EXISTS + - Object already exists + * - 5 + - E_SUSPENDED + - Object already exists + * - 6 + - E_UNSUSPENDED + - Object is already unsuspended + * - 7 + - E_INUSE + - Object can't be deleted because it is used by another object + * - 8 + - E_LIMIT + - Object cannot be created because of hosting package limits + * - 9 + - E_PASSWORD + - Wrong password + * - 10 + - E_FORBIDEN + - Object cannot be accessed by this user + * - 11 + - E_DISABLED + - Subsystem is disabled + * - 12 + - E_PARSING + - Configuration is broken + * - 13 + - E_DISK + - Not enough disk space to complete the action + * - 14 + - E_LA + - Server is to busy to complete the action + * - 15 + - E_CONNECT + - Connection failed. Host is unreachable + * - 16 + - E_FTP + - FTP server is not responding + * - 17 + - E_DB + - Database server is not responding + * - 18 + - E_RRD + - RRDtool failed to update the database + * - 19 + - E_UPDATE + - Update operation failed + * - 20 + - E_RESTART + - Service restart failed + \ No newline at end of file diff --git a/admin_docs/rest_api.rst b/admin_docs/api/rest_api.rst similarity index 90% rename from admin_docs/rest_api.rst rename to admin_docs/api/rest_api.rst index b953873..6f0cf94 100644 --- a/admin_docs/rest_api.rst +++ b/admin_docs/api/rest_api.rst @@ -1,12 +1,7 @@ ################################## -REST API +Examples ################################## -The Hestia WEB API is available to perform core functions of the Control Panel. We use it internaly to synchronyze DNS clusters, to integrate WHMC billing system and to reset mail account passwords in Roundcube. The API can be used as well to create new user accounts, domains, databases or even to build an alternative web interface. - -This reference provides php code samples demonstrating how you can seamlessly integrate API into your application or script. However you can use other languages to commmunicate with API. - - ************************************************ Create User Account ************************************************ @@ -648,78 +643,3 @@ Check Username and Password .catch(function (error) { console.log(error); }); - -************************************************ -Return Codes -************************************************ - -.. list-table:: - :header-rows: 1 - - * - VALUE - - NAME - - COMMENT - * - 0 - - OK - - Command has been successfuly performed - * - 1 - - E_ARGS - - Not enough arguments provided - * - 2 - - E_INVALID - - Object or atgument is not valid - * - 3 - - E_NOTEXIST - - Object doesn't exist - * - 4 - - E_EXISTS - - Object already exists - * - 5 - - E_SUSPENDED - - Object already exists - * - 6 - - E_UNSUSPENDED - - Object is already unsuspended - * - 7 - - E_INUSE - - Object can't be deleted because it is used by another object - * - 8 - - E_LIMIT - - Object cannot be created because of hosting package limits - * - 9 - - E_PASSWORD - - Wrong password - * - 10 - - E_FORBIDEN - - Object cannot be accessed by this user - * - 11 - - E_DISABLED - - Subsystem is disabled - * - 12 - - E_PARSING - - Configuration is broken - * - 13 - - E_DISK - - Not enough disk space to complete the action - * - 14 - - E_LA - - Server is to busy to complete the action - * - 15 - - E_CONNECT - - Connection failed. Host is unreachable - * - 16 - - E_FTP - - FTP server is not responding - * - 17 - - E_DB - - Database server is not responding - * - 18 - - E_RRD - - RRDtool failed to update the database - * - 19 - - E_UPDATE - - Update operation failed - * - 20 - - E_RESTART - - Service restart failed - diff --git a/admin_docs/backups.rst b/admin_docs/backups.rst index eb05eb6..ed4d1cb 100644 --- a/admin_docs/backups.rst +++ b/admin_docs/backups.rst @@ -2,6 +2,42 @@ Backups / Restore ############################# +************************************************ +How to move a user to a new server? +************************************************ + +The current restore function accept both VestaCP and HestiaCP generated backups + +#. Make a user backup on the old server. In this example we will use username as the reference. + +.. code-block:: bash + + v-backup-user username + +#. Copy tarball to the new server and place it in the /backup directory + +.. code-block:: bash + + scp /home/backup/username.2020.01.01-00-00.tar root@host.domain.tld:/backup/ + +#. Restore backup on the new server + +.. code-block:: bash + + v-restore-user username username.2020.01.01-00-00.tar + +Want to restore a different user? + +Use + +.. code-block:: bash + + v-restore-user newusername username.2020.01.01-00-00.tar + +User accounts that don not exist will be created. + + + ************************************************ What kind of backups are able to be restored ************************************************ diff --git a/admin_docs/cron.rst b/admin_docs/cron.rst new file mode 100644 index 0000000..2a3b627 --- /dev/null +++ b/admin_docs/cron.rst @@ -0,0 +1,9 @@ +##################### +Cronjobs +##################### + +***************************************** +Can I update my cronjobs via crontab -e? +***************************************** + +No currently HestiaCP overwrites every time we upgrade or you restore the user account the crontab -e page. Also changes will not get saved in backups. \ No newline at end of file diff --git a/admin_docs/database.rst b/admin_docs/database.rst new file mode 100644 index 0000000..7e79c50 --- /dev/null +++ b/admin_docs/database.rst @@ -0,0 +1,47 @@ +############################### +Database +############################### + +************************************************ +How to setup a remote database server +************************************************ + +#. It is assumed you already have your second server up and running +#. On your Hestia Server run the following command + +.. code-block:: bash + + v-add-database-host mysql new-server.com root password + +Mysql maybe replaced by the PostgreSQL + +#. To make sure database has been added run following command + +.. code-block:: bash + + v-list-database-hosts + +*************************************************************** +Why I can't use :samp:`http://ip/phpmyadmin/` +*************************************************************** + +For security reason we have decided to disable this option + +Please use :samp:`https://host.domain.tld/phpmyadmin/` + + +*************************************************************** +How can I connect from a remote location to the database +*************************************************************** + +By default connections are disabled open port 3306 in the firewall. Open port 3306 in the firewall + +.. image:: ../images/ipset/ipset-3.png + :width: 350 + :align: center + :height: 391px + :alt: Add Firewall rule + +Then edit /etc/mysql/mariadb.conf.d/50-server.cnf + +And set bind-address = 0.0.0.0 or bind-address = "your.server.ip.address" diff --git a/admin_docs/dns.rst b/admin_docs/dns.rst new file mode 100644 index 0000000..71dc53c --- /dev/null +++ b/admin_docs/dns.rst @@ -0,0 +1,48 @@ +############################### +DNS Management / DNS server +############################### + +************************************************ +How to setup a DNS Cluster +************************************************ + +If you are looking for the options to minimize DNS-related downtime or the way to manage dns across all server you have, you might consider to set up dns cluster. + +#. Create user **dns-cluster** on a server which will be used as dns slave +#. Run following command on a master + +.. code-block:: bash + + v-add-remote-dns-host slave.yourhost.com 8083 admin p4sw0rd + +Password and host name should be replaced with relevant data of course. + +Alternatively you can run on the slave server the following command + +.. code-block:: bash + + v-generate-api-key + +This will generate an API key. Replace the username "admin" with the generated key. This will keep the ability to change the admin password without issues in the future. + +.. code-block:: bash + + v-add-remote-dns-host slave.yourhost.com 8083 api_key + +This way you can set up master->slave or master-master-master cluster. There is no limitation on how to chain dns servers. + +************************************************ +Can I seperate DNS accounts by users +************************************************ + +Yes you can just supply the user varibale behind the command. + +.. code-block:: bash + + v-add-remote-dns-host slave.yourhost.com 8083 admin p4sw0rd useraccount + +Or + +.. code-block:: bash + +v-add-remote-dns-host slave.yourhost.com 8083 api_key '' useraccount \ No newline at end of file diff --git a/admin_docs/mail.rst b/admin_docs/mail.rst new file mode 100644 index 0000000..be1f1a0 --- /dev/null +++ b/admin_docs/mail.rst @@ -0,0 +1,66 @@ +####################################### +Email and mail server +####################################### + +*************************************** +I am unable to send email. +*************************************** + +Check first if the port 25 is open for outgoing traffic. A lot of providers close port 25 on default as a security measurement to combat spam. + +Run the following command in commad line: + +.. code-block:: bash + + telnet ASPMX.L.GOOGLE.COM 25 + +If the connection was successfull you will see: + +.. code-block:: bash + + Trying 2a00:1450:400c:c00::1b... + Connected to ASPMX.L.GOOGLE.COM. + Escape character is '^]'. + 220 mx.google.com ESMTP a7si1253985wrr.455 - gsmtp + +If not you have 2 options: + 1. Contact you provider and ask them to open port 25 for outgoing traffic. + 2. Setup a mail relay under the mail domain settings or set it up generally for the server in system settings. For this you to use an SMTP relay service like: + - https://aws.amazon.com/ses/ + - https://www.smtp2go.com + + +*************************************** +I am unable to receive email. +*************************************** + +If yo are unable to receive email make sure you have setup your DNS propperly. If you are using Cloudflare disable the use of the proxy for the mail domain. + +When you are done you can check via https://mxtoolbox.com/MXLookup.aspx. + +*************************************** +How to install Rainloop +*************************************** + +You can install rainloop via the following command + +.. code-block:: bash + + v-add-sys-rainloop + +***************************************** +Can I login into the backend of Rainloop +***************************************** + +In the root folder is an file located called .rainloop containing the username and password + +.. code-block:: bash + + Username: admin_f0e5a5aa + Password: D0ung4naLOptuaa + Secret key: admin_f0e5a5aa + +You can access the admin via https://webmail.domain.com/?admin_f0e5a5aa + +And use the data supplied above. When not needed feel free to remove this file. + diff --git a/admin_docs/server_management.rst b/admin_docs/server_management.rst deleted file mode 100644 index edba619..0000000 --- a/admin_docs/server_management.rst +++ /dev/null @@ -1,352 +0,0 @@ -############################### -Server management -############################### - -************************************************ -How to setup a DNS Cluster -************************************************ - -If you are looking for the options to minimize DNS-related downtime or the way to manage dns across all server you have, you might consider to set up dns cluster. - -#. Create user **dns-cluster** on a server which will be used as dns slave -#. Run following command on a master - -.. code-block:: bash - - v-add-remote-dns-host slave.yourhost.com 8083 admin p4sw0rd - -Password and host name should be replaced with relevant data of course. - -Alternatively you can run on the slave server the following command - -.. code-block:: bash - - v-generate-api-key - -This will generate an API key. Replace the username "admin" with the generated key. This will keep the ability to change the admin password without issues in the future. - -.. code-block:: bash - - v-add-remote-dns-host slave.yourhost.com 8083 api_key - -This way you can set up master->slave or master-master-master cluster. There is no limitation on how to chain dns servers. - -************************************************ -How to setup a remote database server -************************************************ - -#. It is assumed you already have your second server up and running -#. On your Hestia Server run the following command - -.. code-block:: bash - - v-add-database-host mysql new-server.com root password - -Mysql maybe replaced by the PostgreSQL - -#. To make sure database has been added run following command - -.. code-block:: bash - - v-list-database-hosts - - -************************************************ -How do Web templates work? -************************************************ - -.. warning:: - Modifying templates could cause errors on the server and services that are not able to reload or start. - -Every time you will rebuild the user or domain the config files of the domain will be over written by the new templates. This is done by default during update of HestiaCP or it can be initiated by the admin or by modifying settings by the user. - -The templates can be found in the /data/templates/ directory in the install folder - -.. list-table:: Template locations - :widths: 25 75 - :header-rows: 1 - - * - Service - - Location - * - Nginx (Proxy) - - /usr/local/hestia/data/templates/web/nginx/ - * - Nginx - PHP FPM - - /usr/local/hestia/data/templates/web/nginx/php-fpm/ - * - Apache2 (Legacy / mod-php ) - - /usr/local/hestia/data/templates/web/apache2/ - * - Apache2 - PHP FPM - - /usr/local/hestia/data/templates/web/apache2/php-fpm/ - * - PHP-FPM - - /usr/local/hestia/data/templates/web/php-fpm/ - -When editing it is the best practice to copy the template before editing. As the default templates will reset after update of HestiaCP - -.. code-block:: bash - - cp original.tpl new.tpl - cp original.stpl new.stpl - cp original.sh new.sh - -.. note:: - Modifying any default templates can cause issues in the future as there are commonly overwritten during updates. - -When you are done modifying enable the template with the selected domain from the control panel. - -After modifying existing template you need to rebuild user configuration. This can be done using v-rebuild-user command or bulk operation in the web interface (drop down list on a "User" page). - -------------------- -Available variables -------------------- - -.. list-table:: Variables - :widths: 20 30 50 - :header-rows: 1 - - * - Name - - Example - - Description - * - %ip% - - 123.123.123.123 - - IP Address of Server - * - %proxy_port% - - 80 - - Port of Proxy - * - %proxy_port_ssl% - - 443 - - Port of Proxy (SSL) - * - %web_port% - - 80 or 8080 - - Port of Webserver - * - %web_ssl_port% - - 443 or 8443 - - Port of Webserver (SSL) - * - %domain% - - domain.tld - - Domain - * - %domain_idn% - - domain.tld - - Domain (Internationalised) - * - %alias_idn% - - alias.domain.tld - - Alias Domain (Internationalised) - * - %docroot% - - /home/username/web/public_html/ - - Document root of domain - * - %sdocroot% - - /home/username/web/public_shtml/ - - Private root of domain - * - %ssl_pem% - - /usr/local/hestia/data/user/username/ssl - - Location of SSL Certificate - * - %ssl_key% - - /usr/local/hestia/data/user/username/ssl - - Location of SSL Key - * - %web_system% - - Nginx / Apache - - Software used as Webserver - * - %home% - - /home - - Default home directory - * - %user% - - username - - Username of user - * - %user% - - username - - Username of user - * - %backend_lsnr% - - proxy:fcgi://127.0.0.1:9000 - - Your default FPM Server - * - %proxy_extentions% - - List of extensions - - All extension that should be handled by the proxy server - - -%sdocroot% can also be set to %docroot% with settings - -************************************************ -How can I change settings for a specific domain -************************************************ - -With the switch to PHP-FPM there are currently 2 different ways. - -1# Using user.ini in the directory -2# Via PHP-FPM pool config - -Config templates for the PHP pool can be found in - -.. list-table:: Template locations - :widths: 25 75 - :header-rows: 1 - - * - Service - - Location - * - PHP-FPM - - /usr/local/hestia/data/templates/web/php-fpm/ - -Due to the fact we use multi PHP we need to recognise the PHP version to be used. There for we follow the following naming. - -.. code-block:: bash - - YOURNAME-PHP-X_Y.tpl - -There X_Y is your PHP version - -************************************************ -How do DNS templates work? -************************************************ - -DNS templates can be found in - -.. list-table:: Templates locations - :widths: 25 75 - :header-rows: 1 - - * - Service - - Location - * - DNS - - /usr/local/hestia/data/templates/dns/ - - -Variables that can be used are - -.. list-table:: Available variables - :widths: 25 25 50 - :header-rows: 1 - - * - Name - - Example - - Description - * - %ns1% - - ns1.nameserver.tld - - Name server 1 - * - %ns2% - - ns2.nameserver.tld - - Name server 2 - * - %ip% - - 123.123.123.123 - - Ip address of the server or Dedicated ip - * - %domain% - - domain.tld - - Domain of the user - * - %time% - - 12:00:00 - - Time of creation - * - %date% - - 01-01-2020 - - Time of creation - -Templates can support up to 8 name servers with with %nsx% x could be up to maximum of 8 - -********************************************************* -Where can I find more information about the config files -********************************************************* - -A good starting point for every software check the creator - -* For Nginx `NGINX Docs `_ -* For Apache2 `Apache Docs `_ -* For PHP FPM `PHP Docs `_ - -You could also try `our Forum `_ - -*************************************************************** -How to install additional PHP packages / Modules -*************************************************************** - -.. code-block:: bash - - apt-get install php-package-name - - -For example - -.. code-block:: bash - - apt-get install php-memcached php-redis - -Will install php-memcached and php-redis including the required additional packages for PHP. - -Incase you use PHP-FPM you don't have to do anything. - -*************************************************************** -IPTables How can I allow/deny an IP to all ports -*************************************************************** - -By default after each restart Hestia will clear the current iptables - -To allow an IP to all ports (Or block) - -Use the following command - -.. code-block:: bash - - v-add-firewall-rule ACTION IP PORT [PROTOCOL] [COMMENT] [RULE] - - v-add-firewall-rule 'accept' '123.123.123.123' '0' # Port 0 matches all ports - -Also via interface it is possible just enter 0 as port number - -************************************************ -Can I use HestiaCP behind Cloudflare CDN? -************************************************ - -By default `Cloudflare `_ supports only a limited number of ports - -To change the port you can run the command - -.. code-block:: bash - - v-change-sys-port 2083 - -Or you can disable the proxy of Cloudflare - - -*************************************************************** -Why I can't use :samp:`http://my.ip.adress/phpmyadmin/` -*************************************************************** - -For security reason we have decided to disable this option - -Please use :samp:`https://host.domain.tld/phpmyadmin/` - -*************************************************************** -How can I enable / Disable the filemanager -*************************************************************** - -By an new install the filemanager will be enabled by default - -For updates please run the following command - -.. code-block:: bash - - v-add-sys-filemanager - -To disable the file manager please run - -.. code-block:: bash - - v-delete-sys-filemanager - -*************************************************************** -How to remove unused ethernet ports from RRD -*************************************************************** - -.. code-block:: bash - - nano /usr/local/hestia/conf/hestia.conf - -Add the following line: - -.. code-block:: bash - - RRD_IFACE_EXCLUDE='lo' - -Add a other network port as comma separated list - -.. code-block:: bash - - rm /usr/local/hestia/web/rrd/net/* - systemctl restart hestia - - - diff --git a/admin_docs/settings.rst b/admin_docs/settings.rst new file mode 100644 index 0000000..d7fbdac --- /dev/null +++ b/admin_docs/settings.rst @@ -0,0 +1,64 @@ +######################## +Server setting / Config +######################## + +.. toctree:: + :maxdepth: 2 + :glob: + + settings/filemanager.rst + settings/firewall.rst + + +********************************************************* +Where can I find more information about the config files +********************************************************* + +A good starting point for every software check the creator + +* For Nginx `NGINX Docs `_ +* For Apache2 `Apache Docs `_ +* For PHP FPM `PHP Docs `_ + +You could also try `our Forum `_ + + + +************************************************ +Can I use HestiaCP behind Cloudflare CDN? +************************************************ + +By default `Cloudflare `_ supports only a limited number of ports + +To change the port you can run the command + +.. code-block:: bash + + v-change-sys-port 2083 + +Or you can disable the proxy of Cloudflare + + +*************************************************************** +How to remove unused ethernet ports from RRD +*************************************************************** + +.. code-block:: bash + + nano /usr/local/hestia/conf/hestia.conf + +Add the following line: + +.. code-block:: bash + + RRD_IFACE_EXCLUDE='lo' + +Add a other network port as comma separated list + +.. code-block:: bash + + rm /usr/local/hestia/web/rrd/net/* + systemctl restart hestia + + + diff --git a/admin_docs/filemanager.rst b/admin_docs/settings/filemanager.rst similarity index 100% rename from admin_docs/filemanager.rst rename to admin_docs/settings/filemanager.rst diff --git a/admin_docs/settings/firewall.rst b/admin_docs/settings/firewall.rst new file mode 100644 index 0000000..d0492db --- /dev/null +++ b/admin_docs/settings/firewall.rst @@ -0,0 +1,111 @@ +############################# +Firewall / Fail2ban / Ipset +############################# + +*************************************************************** +IPTables How can I allow/deny an IP to all ports +*************************************************************** + +By default after each restart Hestia will clear the current iptables + +To allow an IP to all ports (Or block) + +Use the following command + +.. code-block:: bash + + v-add-firewall-rule ACTION IP PORT [PROTOCOL] [COMMENT] [RULE] + + v-add-firewall-rule 'accept' '123.123.123.123' '0' # Port 0 matches all ports + +Also via interface it is possible just enter 0 as port number + +**************************************** +How do I setup ip set black / whitelist +**************************************** + +IPset are large lists of ip adresses / subnets. They can be used for black/white lists. + +Go to "Server" (Cogs icon) then click on Configure -> Firewall -> Manage IP set and you will see the following page. + +.. image:: ../../images/ipset/ipset-1.png + :width: 656px + :align: center + :height: 150px + :alt: List IP List + +Click on "Add IP list" + +.. image:: ../../images/ipset/ipset-2.png + :width: 350px + :align: center + :height: 303px + :alt: Add IP List + +Name provide a name for IP list +For data source you are able to us the following opions: + +1. Url http://ipverse.net/ipblocks/data/countries/nl.zone (or https) +2. Script: script:/usr/local/hestia/install/deb/firewall/ipset/blacklist.sh If you use your own scripts make sure you chmod to 775. +3. File: file:/location/of/file + +IP Version. Currently we only support ip v4 how ever a future release will include for ip v6. + +Auto update Yes / No + +And click on save. + +The go to the "Firewall" and click on "Add Rule" + +.. image:: ../../images/ipset/ipset-3.png + :width: 350 + :align: center + :height: 391px + :alt: Add Firewall rule + +Set action to block / allow depending on your needs. +Protocol to the protocol you want to block/allow +Ports to the ports you want to block / allow. +Ip Address / IP list Select the IP set you want to use +You can also use ipset:name + +And click on "Save". + +******************************************* +My IP set doesn't work +******************************************* + +An IP set must at least contain 10 IP / Ip ranges. + +******************************************* +Can I combine multiple sources in one? +******************************************* + +If you want to combine multiple ip sources together it can be done via de following script: + +.. code-block:: bash + + #!/bin/bash + + BEL=( + "http://ipverse.net/ipblocks/data/countries/be.zone" + "http://ipverse.net/ipblocks/data/countries/nl.zone" + "http://ipverse.net/ipblocks/data/countries/lu.zone" + ) + + IP_BEL_TMP=$(mktemp) + for i in "${BEL[@]}"; do + IP_TMP=$(mktemp) + (( HTTP_RC=$(curl -L --connect-timeout 10 --max-time 10 -o "$IP_TMP" -s -w "%{http_code}" "$i") )) + if (( HTTP_RC == 200 || HTTP_RC == 302 || HTTP_RC == 0 )); then # "0" because file:/// returns 000 + command grep -Po '^(?:\d{1,3}\.){3}\d{1,3}(?:/\d{1,2})?' "$IP_TMP" | sed -r 's/^0*([0-9]+)\.0*([0-9]+)\.0*([0-9]+)\.0*([0-9]+)$/\1.\2.\3.\4/' >> "$IP_BEL_TMP" + elif (( HTTP_RC == 503 )); then + echo >&2 -e "\\nUnavailable (${HTTP_RC}): $i" + else + echo >&2 -e "\\nWarning: curl returned HTTP response code $HTTP_RC for URL $i" + fi + rm -f "$IP_TMP" + done + + sed -r -e '/^(0\.0\.0\.0|10\.|127\.|172\.1[6-9]\.|172\.2[0-9]\.|172\.3[0-1]\.|192\.168\.|22[4-9]\.|23[0-9]\.)/d' "$IP_BEL_TMP"|sort -n|sort -mu + rm -f "$IP_BEL_TMP" \ No newline at end of file diff --git a/admin_docs/user_management.rst b/admin_docs/user_management.rst deleted file mode 100644 index e207676..0000000 --- a/admin_docs/user_management.rst +++ /dev/null @@ -1,38 +0,0 @@ -############################### -User management -############################### - -************************************************ -How to move a user to a new server? -************************************************ - -The current restore function accept both VestaCP and HestiaCP generated backups - -#. Make a user backup on the old server. In this example we will use username as the reference. - -.. code-block:: bash - - v-backup-user username - -#. Copy tarball to the new server and place it in the /backup directory - -.. code-block:: bash - - scp /home/backup/username.2020.01.01-00-00.tar root@host.domain.tld:/backup/ - -#. Restore backup on the new server - -.. code-block:: bash - - v-restore-user username username.2020.01.01-00-00.tar - -Want to restore a different user? - -Use - -.. code-block:: bash - - v-restore-user newusername username.2020.01.01-00-00.tar - -User accounts that don not exist will be created. - diff --git a/admin_docs/web.rst b/admin_docs/web.rst new file mode 100644 index 0000000..443df0a --- /dev/null +++ b/admin_docs/web.rst @@ -0,0 +1,171 @@ +################################# +Web domains and SSL Certicates +################################# + +.. toctree:: + :maxdepth: 2 + :glob: + + web/fastcgi.rst + web/ssl_certificates.rst + +************************************************ +How do Web templates work? +************************************************ + +.. warning:: + Modifying templates could cause errors on the server and services that are not able to reload or start. + +Every time you will rebuild the user or domain the config files of the domain will be over written by the new templates. This is done by default during update of HestiaCP or it can be initiated by the admin or by modifying settings by the user. + +The templates can be found in the /data/templates/ directory in the install folder + +.. list-table:: Template locations + :widths: 25 75 + :header-rows: 1 + + * - Service + - Location + * - Nginx (Proxy) + - /usr/local/hestia/data/templates/web/nginx/ + * - Nginx - PHP FPM + - /usr/local/hestia/data/templates/web/nginx/php-fpm/ + * - Apache2 (Legacy / mod-php ) + - /usr/local/hestia/data/templates/web/apache2/ + * - Apache2 - PHP FPM + - /usr/local/hestia/data/templates/web/apache2/php-fpm/ + * - PHP-FPM + - /usr/local/hestia/data/templates/web/php-fpm/ + +When editing it is the best practice to copy the template before editing. As the default templates will reset after update of HestiaCP + +.. code-block:: bash + + cp original.tpl new.tpl + cp original.stpl new.stpl + cp original.sh new.sh + +.. note:: + Modifying any default templates can cause issues in the future as there are commonly overwritten during updates. + +When you are done modifying enable the template with the selected domain from the control panel. + +After modifying existing template you need to rebuild user configuration. This can be done using v-rebuild-user command or bulk operation in the web interface (drop down list on a "User" page). + +------------------- +Available variables +------------------- + +.. list-table:: Variables + :widths: 20 30 50 + :header-rows: 1 + + * - Name + - Example + - Description + * - %ip% + - 123.123.123.123 + - IP Address of Server + * - %proxy_port% + - 80 + - Port of Proxy + * - %proxy_port_ssl% + - 443 + - Port of Proxy (SSL) + * - %web_port% + - 80 or 8080 + - Port of Webserver + * - %web_ssl_port% + - 443 or 8443 + - Port of Webserver (SSL) + * - %domain% + - domain.tld + - Domain + * - %domain_idn% + - domain.tld + - Domain (Internationalised) + * - %alias_idn% + - alias.domain.tld + - Alias Domain (Internationalised) + * - %docroot% + - /home/username/web/public_html/ + - Document root of domain + * - %sdocroot% + - /home/username/web/public_shtml/ + - Private root of domain + * - %ssl_pem% + - /usr/local/hestia/data/user/username/ssl + - Location of SSL Certificate + * - %ssl_key% + - /usr/local/hestia/data/user/username/ssl + - Location of SSL Key + * - %web_system% + - Nginx / Apache + - Software used as Webserver + * - %home% + - /home + - Default home directory + * - %user% + - username + - Username of user + * - %user% + - username + - Username of user + * - %backend_lsnr% + - proxy:fcgi://127.0.0.1:9000 + - Your default FPM Server + * - %proxy_extentions% + - List of extensions + - All extension that should be handled by the proxy server + + +%sdocroot% can also be set to %docroot% with settings + +************************************************ +How can I change settings for a specific domain +************************************************ + +With the switch to PHP-FPM there are currently 2 different ways. + +1. Using user.ini in the directory +2. Via PHP-FPM pool config + +Config templates for the PHP pool can be found in + +.. list-table:: Template locations + :widths: 25 75 + :header-rows: 1 + + * - Service + - Location + * - PHP-FPM + - /usr/local/hestia/data/templates/web/php-fpm/ + +Due to the fact we use multi PHP we need to recognise the PHP version to be used. There for we follow the following naming. + +.. code-block:: bash + + YOURNAME-PHP-X_Y.tpl + +There X_Y is your PHP version + +*************************************************************** +How to install additional PHP packages / Modules +*************************************************************** + +.. code-block:: bash + + apt-get install php-package-name + + +For example + +.. code-block:: bash + + apt-get install php-memcached php-redis + +Will install php-memcached and php-redis including the required additional packages for PHP. + +Incase you use PHP-FPM you don't have to do anything. + + diff --git a/admin_docs/web/fastcgi.rst b/admin_docs/web/fastcgi.rst new file mode 100644 index 0000000..4a57eeb --- /dev/null +++ b/admin_docs/web/fastcgi.rst @@ -0,0 +1,77 @@ +############################################################### +Nginx FastCGI Cache +############################################################### + +FastCGI Cache is an option with in Nginx allowing to cache the out put of FastCGI (in this case php). There will be for a short moment an file created on your server with the contents of the output. If an other user requests the same page Nginx will check if the "age" of the cached file is still valid and if it is true it will send the cached file to to the user. + +FastCGI cache works best for sites get a lot of request and the pages doesn't change that often. (For example an news site). For an more dynamic sites there might be changes required to the configuration or even disabling is required. + +*************************************************************** +Why does software package x and y not work with FastCGI cache +*************************************************************** + +As we have over 20 different templates and we don't use them al we have decided it to release the future and hope in the future the comuntity helps improving the templates with a pull request. + +To disable the FastCGI cache for an certain template you can set the $no_cache variable to 1 + +.. code-block:: bash + + if ($http_cookie ~* "comment_author|wordpress_[a-f0-9]+|wp-postpass|wordpress_no_cache|wordpress_logged_in|woocommerce_items_in_cart|woocommerce_cart_hash|PHPSESSID") { + set $no_cache 1; + } + +*************************************************************** +How do I enable FastCGI cache for my custom template +*************************************************************** + +Within the block where you call php / fastcgi pass + +.. code-block:: bash + + location ~ [^/]\.php(/|$) { + fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; + try_files $uri =404; + fastcgi_pass %backend_lsnr%; + fastcgi_index index.php; + include /etc/nginx/fastcgi_params; + } + +And add the following lines under the ``include /etc/nginx/fastcgi_params;`` + +.. code-block:: bash + + include %home%/%user%/conf/web/%domain%/nginx.fastcgi_cache.conf*; + + if ($request_uri ~* "/path/with/exceptions/regex/whatever") { + set $no_cache 1; + } + +*************************************************************** +How can I see if FastCGI Cache is working +*************************************************************** + +.. code-block:: bash + + v-add-fastcgi-cache user domain.tld 5m yes yes + +It will add an X-STATUS header to the return data where it can be a miss, hit or bypass. + +- Hit Requested file came out the cache +- Miss Requested file was missing in the cache or was to old +- Bypass Cache was bypassed (no_cache) variable was set + +*************************************************************** +How can I clear the cache? +*************************************************************** + +When FastCGI cache is enabled an button is added to "Edit" Web where you can clear the cache or use the command: + +.. code-block:: bash + + v-purge-nginx-cache user domain.tld + +*************************************************************** +Why do I don't have the option to use FastCGI cache +*************************************************************** + +FastCGI cache is an option for Nginx mode only. If you are using Nginx + Apache2 you can enable proxy caching template and proxy cache will enable. Functions almost the same. Proxy cache will also work in case you use a docker image or nodejs. \ No newline at end of file diff --git a/admin_docs/ssl_certificates.rst b/admin_docs/web/ssl_certificates.rst similarity index 54% rename from admin_docs/ssl_certificates.rst rename to admin_docs/web/ssl_certificates.rst index 21b3e04..9d6537f 100644 --- a/admin_docs/ssl_certificates.rst +++ b/admin_docs/web/ssl_certificates.rst @@ -38,8 +38,66 @@ Error Message rateLimited The Rate limit of the maximum requests have been passed. Please check https://crt.sh for how active certificates you have. ================ ================================================================================== - - + +************************************************** +Error: Let's Encrypt validation status 400. +************************************************** + +When requesting an SSL certificate the following error is often seen: + +Error: Let's Encrypt validation status 400. Details: Unable to update challenge :: authorization must be pending +means + +It could mean multiple things: + +1. Cloudflare proxy is enabled and SSL is set too strict. +2. Nginx / Apache2 is not reloading / Issue with an template +3. IPv6 is setup. Disable IPV6 in DNS +4. Wrong / Incorrect template. + +In the future we hope to improve debugging but so far the easiest currently is: + +Go to /var/log/hestia/ and when you run the command you will multiple log files: + +``LE-{user}-{domain}-{date}-{time}.log`` + +Open this log file an go to "Step 5" + +You will see something like. + +.. code-block:: bash + + ==[Step 5]== + - status: 200 + - nonce: 0004EDQMty6_ZOb1BdRQSc-debiHXGXaXbZuyySFU2xoogk + - validation: pending + - details: + - answer: HTTP/2 200 + server: nginx + date: Wed, 21 Apr 2021 22:32:16 GMT + content-type: application/json + content-length: 186 + boulder-requester: 80260362 + cache-control: public, max-age=0, no-cache + link: ;rel="index" + link: ;rel="up" + location: https://acme-v02.api.letsencrypt.org/acme/chall-v3/12520447717/scDRXA + replay-nonce: 0004EDQMty6_ZOb1BdRQSc-debiHXGXaXbZuyySFU2xoogk + x-frame-options: DENY + strict-transport-security: max-age=604800 + + { + "type": "http-01", + "status": "pending", + "url": "https://acme-v02.api.letsencrypt.org/acme/chall-v3/12520447717/scDRXA", + "token": "9yriok5bpLtV__m-rZ8f2tQmrfeQli0tCxSj4iNkv2Y" + } + +If you follow https://acme-v02.api.letsencrypt.org/acme/chall-v3/12520447717/scDRXA + +You will get more info what went wrong. + + ************************************************** Can I request a SSL Certificate with Lets Encrypt ************************************************** @@ -48,7 +106,7 @@ Yes, you are able to enable Lets Encrypt even with Cloudflare how ever it need s #. Disable Cloudflare proxy of you domain. #. Wait Approx 5 min due to caches by several name servers -#. Request a Certificate via Control pannel or use the CLI command +#. Request a Certificate via Control panel or use the CLI command #. Enable proxy #. Switch over to Full (strict) (Go to SSL/TLS Tab) diff --git a/images/api/api-1.png b/images/api/api-1.png new file mode 100644 index 0000000..6f12c7b Binary files /dev/null and b/images/api/api-1.png differ diff --git a/images/ipset/ipset-1.png b/images/ipset/ipset-1.png new file mode 100644 index 0000000..ae8abb7 Binary files /dev/null and b/images/ipset/ipset-1.png differ diff --git a/images/ipset/ipset-2.png b/images/ipset/ipset-2.png new file mode 100644 index 0000000..77f9314 Binary files /dev/null and b/images/ipset/ipset-2.png differ diff --git a/images/ipset/ipset-3.png b/images/ipset/ipset-3.png new file mode 100644 index 0000000..1cc7a37 Binary files /dev/null and b/images/ipset/ipset-3.png differ