https://wiki.sympl.io/w/api.php?action=feedcontributions&user=Kelduum&feedformat=atomSympl Wiki - User contributions [en-gb]2024-03-29T13:23:19ZUser contributionsMediaWiki 1.41.0https://wiki.sympl.io/w/index.php?title=Alternate_PHP_Versions&diff=5031Alternate PHP Versions2024-03-22T08:50:21Z<p>Kelduum: </p>
<hr />
<div>{{Community Documentation}}<br />
<br />
Sympl only natively supports the Debian-bundled PHP, but with a bit of poking, it's easy to give it support for other PHP versions with PHP-FPM which ''doesn't'' break the usual Sympl stuff.<br />
<br />
'''If you're running Sympl 12 or above, you should use the built-in PHP options as that will manage this for you in less dangerous way!'''<br />
<br />
== Important Information ==<br />
<br />
This involves using a third-party (not official Debian) repository, which means that security fixes and other changes ''may'' take a little longer to appear in all versions.<br />
<br />
However, the [https://deb.sury.org/ repository below] is maintained by Ondřej Surý, who has been a Debian Developer since 2000, and packaged PHP for Debina since 2005, so it's considered safe in most cases.<br />
<br />
It's also important to note that installing this will mean you have some newer packages than typical, you will not automatically receive security updates, and you may encounter issues with Debian or Sympl if not careful, so '''''this is not fully suitable for production settings'''''.<br />
<br />
== Setting It Up ==<br />
<br />
Set this variable to the required PHP version:<br />
<br />
<code>want_version="'''php8.0'''"</code><br />
<br />
You should then be fine to copy and paste these lines, one at a time...<br />
<br />
<pre><br />
# Get the current version running with mod_php<br />
php_version="$( dpkg -l 'libapache2-mod-php[0-9]*' | grep '^ii' | cut -d '-' -f '3' | awk '{ print $1 }' | sort -u )"<br />
# List the relevant php modules so we install the same ones<br />
php_packages="fpm $( dpkg -l "$php_version*" | grep '^ii' | cut -d '-' -f '2' | awk '{ print $1 }' )"<br />
<br />
# Add sury repo if not already there<br />
if [ ! -f /etc/apt/sources.list.d/php.list ] || [ ! -f /etc/apt/preferences.d/sury-php ]; then<br />
apt update<br />
apt -y install apt-transport-https lsb-release ca-certificates curl<br />
curl -sSLo /usr/share/keyrings/deb.sury.org-php.gpg https://packages.sury.org/php/apt.gpg<br />
sh -c 'echo "deb [signed-by=/usr/share/keyrings/deb.sury.org-php.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list'<br />
fi<br />
apt update<br />
<br />
# Enable apache mod<br />
a2enmod proxy_fcgi<br />
<br />
# Attempt to install php-fpm with the relevant packages<br />
<br />
for package in $php_packages; do<br />
echo ---- $package ----<br />
apt -y install $want_version-$package<br />
done<br />
</pre><br />
<br />
Note that some packages such as <code>php8.0-json</code> are virtual packages, so may not be able to be installed normally. This will usually be okay.<br />
<br />
== Enabling ==<br />
<br />
Set this variable to be the domain you want to swap the PHP version on:<br />
<br />
<code>domain="'''example.com'''"</code><br />
<br />
<code>want_version="'''php8.0'''"</code><br />
<br />
Swap the config to use the new PHP version:<br />
<pre><br />
# Create apache include dir<br />
mkdir -p /srv/$domain/config/apache.d<br />
echo "<br />
<FilesMatch \".+\.ph(ar|p|tml)$\"><br />
SetHandler \"proxy:unix:/run/php/$want_version-fpm.sock|fcgi://localhost\"<br />
</FilesMatch><br />
<FilesMatch \".+\.phps$\"><br />
# Deny access to raw php sources by default<br />
# To re-enable it's recommended to enable access to the files<br />
# only in specific virtual host or directory<br />
Require all denied<br />
</FilesMatch><br />
# Deny access to files without filename (e.g. '.php')<br />
<FilesMatch \"^\.ph(ar|p|ps|tml)$\"><br />
Require all denied<br />
</FilesMatch><br />
" > /srv/$domain/config/apache.d/php-fpm.conf<br />
<br />
# Set the permisions<br />
chown sympl:sympl /srv/$domain/config/apache.d /srv/$domain/config/apache.d/php-fpm.conf<br />
<br />
# Make the new config live<br />
sympl-web-configure ; service apache2 reload</pre><br />
<br />
At this point, a simple <code>phpinfo()</code> on the relevant site should report the relevant PHP version.<br />
<br />
<br />
[[Category:How To]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Upgrading_Sympl&diff=5030Upgrading Sympl2024-02-28T09:15:33Z<p>Kelduum: /* Problems */</p>
<hr />
<div>Upgrading Sympl versions is a little more complicated than a standard [[Debian]] upgrade but has been tested thoroughly with servers using the [https://www.mythic-beasts.com Mythic Beasts] Debian/Sympl images.<br />
<br />
Unfortunately this guide doesn't cover other hosting providers, as there tend to be small differences in packages and configurations between them and you may encounter other prompts during the upgrade.<br />
<br />
Note that this is different the the typical "update" via running <code>sympl update</code>. That will update the Sympl to the most recent versions of each package on the same major version while this "upgrade" is for upgrading Sympl and Debian major versions (e.g. 11 to 12).<br />
<br />
Upgrades of Debian Stretch (Sympl 9) and Raspbian/Raspberry Pi OS are not supported at this time.<br />
<br />
If you have installed any other packages yourself you may be given other prompts and these additional packages may have compatibility problems, but you should be able to find support for these.<br />
<br />
==Assumptions==<br />
This guide makes the following assumptions:<br />
<br />
*You're familiar with SSH and running commands as the <code>root</code> user.<br />
*You're using a Mythic Beasts virtual or dedicated server.<br />
*Sympl was installed either from an image or using the installer.<br />
*If you have installed any other packages yourself, you can answer their upgrade questions.<br />
*All sites are confirmed to be compatible with the new [PHP] and [MariaDB] versions.<br />
*You're prepared for 30-60 minutes downtime on the server while the upgrade takes place. You may wish to put critical sites into a maintenance mode before starting to ensure no changes take place.<br />
*You have read this entire page before you start the upgrade!<br />
<br />
If any of the above ''aren't'' true you can continue but you may run into problems or break the server in unusual ways, and this is '''not a configuration we can support'''.<br />
<br />
==Before starting==<br />
<br />
*As with any major changes you should first ensure that you have full backups separate from the existing server, that they contain all the relevant information and that you can restore from them in the event the process goes wrong. If using the built-in Sympl backups, ensure you have an off-server copy of the full <code>/var/backups</code> directory.<br />
*Apply any pending upgrades for the current setup:<br />
<pre><br />
sudo apt -y update<br />
sudo apt -y upgrade<br />
sudo apt -y dist-upgrade<br />
sudo sympl update<br />
</pre><br />
<br />
*Reboot the server to ensure it is working normally and you have a stable platform for the update:<br />
<pre>shutdown -r now</pre><br />
<br />
*Where possible, put any sites into maintenance mode to ensure no changes are lost.<br />
*Take a final backup before starting the upgrade process. If using Sympl backups, use <code>sudo backup2l -b</code> to make a new backup then ensure you have a fresh copy of the <code>/var/backups</code> directory. You also may want to take a snapshot of the server so you can quickly roll back.<br />
<br />
==Upgrading==<br />
<br />
=== Sympl 10 to Sympl 11===<br />
<br />
This upgrade will move from PHP 7.3 to PHP 7.4, and replace [[Webalizer]] (which produces web traffic stats) with [[AWFfull]] - the format of the web traffic statistics generated are incompatible, so stats will be generated without any history.<br />
<br />
If at any point you experience a problem with the below you should restore from the most recent backup. <br />
<br />
*Log into the server as <code>root</code>, or log in as <code>sympl</code> and use <code>sudo su -</code> to swap to the <code>root</code> user.<br />
*Replace the current apt sources for Sympl to point to buster:<br />
<pre><br />
sed 's|buster|bullseye|g' /etc/apt/sources.list.d/sympl_buster.list > /etc/apt/sources.list.d/sympl_bullseye.list && rm /etc/apt/sources.list.d/sympl_buster.list<br />
</pre><br />
<br />
*Move the existing sources.list for Debian out of the way:<br />
<pre><br />
mv /etc/apt/sources.list /etc/apt/sources.list_buster_$( date +%s )<br />
</pre><br />
<br />
*Create a new sources list for bullseye:<br />
<pre><br />
echo "deb http://mirror.mythic-beasts.com/debian/ bullseye main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bullseye main<br />
<br />
deb http://security.debian.org/debian-security bullseye-security main<br />
deb-src http://security.debian.org/debian-security bullseye-security main<br />
<br />
deb http://mirror.mythic-beasts.com/debian/ bullseye-updates main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bullseye-updates main" > /etc/apt/sources.list<br />
</pre><br />
<br />
*Check there will be enough disk space to download the updates:<br />
<pre><br />
apt update<br />
apt -o APT::Get::Trivial-Only=true full-upgrade<br />
</pre><br />
<br />
*If there is a warning about not having enough disk space for the upgrade then stop immediately and either free up space or expand the disk before re-running the above command.<br />
*Downtime will begin here, and you must complete the process in one go.<br />
*Install the package updates that can be installed without installing anything new:<br />
<pre><br />
apt -y upgrade --without-new-pkgs<br />
</pre><br />
<br />
*When prompted, answer '''yes''' to restart services without asking.<br />
*Upgrade all other packages:<br />
<pre><br />
apt -y full-upgrade<br />
</pre><br />
<br />
*When prompted, answer '''yes''' to upgrade the RoundCube database.<br />
*When prompted, answer that you want to keep the existing modified RoundCube configuration file.<br />
*Update the remaining dependencies:<br />
<pre><br />
apt -y install guile-2.2-libs --only-upgrade<br />
</pre><br />
<br />
*Remove the old packages which are no longer needed:<br />
<pre><br />
apt -y autoremove<br />
</pre><br />
<br />
*Update the MariaDB service files to Sympl can interact with them:<br />
<pre><br />
systemctl disable mysql.service<br />
systemctl enable mysql.service<br />
</pre><br />
<br />
*Reconfigure the Pure-FTPd authentication for Sympl:<br />
<pre><br />
rm /etc/pure-ftpd/auth/*<br />
ln -s ../conf/ExtAuth /etc/pure-ftpd/auth/60Ext <br />
</pre><br />
<br />
*Move the old web stats out of the way so new ones can be generated:<br />
<pre><br />
find /srv/*/config -maxdepth 1 -mindepth 1 -name 'stats' | sed 's|/config/stats||' | while read dir; do if [ -d "$dir/public/htdocs/stats" ]; then mv -v "$dir/public/htdocs/stats" "$dir/public/stats_sympl10" ; mkdir "$dir/public/htdocs/stats" ; fi ; done<br />
</pre><br />
<br />
*Reboot the server to ensure all the updates are applied and you're running the new kernel:<br />
<pre><br />
shutdown -r now<br />
</pre><br />
<br />
*Reconnect to the server as <code>root</code> (or <code>sympl</code>, and then swap to root as before)<br />
*Ensure Debian reports the correct version (Release 11):<br />
<br />
lsb_release -a<br />
<br />
*Make sure you're running the new kernel (5.x):<br />
<br />
uname -r<br />
<br />
*Check Sympl was upgraded okay (all versions should start '11.x'):<br />
<br />
dpkg -l 'sympl-*'<br />
<br />
===Sympl 11 to Sympl 12===<br />
<br />
This upgrade will move from PHP 7.4 to PHP 8.2 by default, but with a great deal of new PHP configuration options, allowing you to run a site under various PHP versions.<br />
<br />
If at any point you experience a problem with the below you should restore from the most recent backup. <br />
<br />
*Log into the server as <code>root</code>, or log in as <code>sympl</code> and use <code>sudo su -</code> to swap to the <code>root</code> user.<br />
<br />
* Disable the old Sympl repo<br />
<pre>sed -i 's|^deb.*|#&|' /etc/apt/sources.list.d/sympl_bullseye.list<br />
mv /etc/apt/sources.list.d/sympl_bullseye.list /etc/apt/sources.list.d/disabled-$( date +%s )_sympl_bullseye.list<br />
</pre><br />
<br />
* Disable other old Repos for Debian Bullseye<br />
<pre><br />
sed -i 's|^deb http://packages.mythic-beasts.com/mythic/.*|#&|' /etc/apt/sources.list.d/*.list<br />
sed -i 's|^deb .* bullseye .*|#&|' /etc/apt/sources.list.d/*.list<br />
</pre><br />
<br />
* Add the new Apt Repository for Sympl 12 and add the key.<br />
<pre><br />
echo "deb http://packages.mythic-beasts.com/mythic/ bookworm main" > /etc/apt/sources.list.d/sympl_bookworm.list<br />
wget -q https://mirror.mythic-beasts.com/mythic/support@mythic-beasts.com.gpg.key -O /etc/apt/trusted.gpg.d/support@mythic-beasts.com.asc<br />
</pre><br />
<br />
*Move the existing sources.list for Debian out of the way:<br />
<pre><br />
mv /etc/apt/sources.list /etc/apt/sources.list_bullseye_$( date +%s )<br />
</pre><br />
<br />
*Create a new sources list for bullseye:<br />
<pre><br />
echo "deb http://mirror.mythic-beasts.com/debian/ bookworm main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bookworm main<br />
<br />
deb http://security.debian.org/debian-security bookworm-security main<br />
deb-src http://security.debian.org/debian-security bookworm-security main<br />
<br />
deb http://mirror.mythic-beasts.com/debian/ bookworm-updates main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bookworm-updates main" > /etc/apt/sources.list<br />
</pre><br />
<br />
*Set some options for updates:<br />
<pre><br />
export DEBIAN_FRONTEND=noninteractive <br />
export UCF_FORCE_CONFFNEW=YES<br />
</pre><br />
<br />
*Check there will be enough disk space to download the updates:<br />
<pre><br />
apt update<br />
apt -qq -o APT::Get::Trivial-Only=true full-upgrade 2>&1 | tail -n 3 | grep -v 'Trivial Only'<br />
</pre><br />
<br />
*If there is a warning about not having enough disk space for the upgrade then stop immediately and either free up space or expand the disk before re-running the above command.<br />
*Downtime will begin here, and you must now complete the remainder of this process in one go.<br />
*Install the package updates that can be installed without installing anything new:<br />
<pre><br />
apt -y upgrade --without-new-pkgs<br />
</pre><br />
<br />
*If prompted, answer '''yes''' to restart services without asking.<br />
*Disable the old PHP Apache Module<br />
<pre>a2dismod php7.4</pre><br />
*Upgrade all other packages:<br />
<pre><br />
apt -o Dpkg::Options::="--force-confnew" -y full-upgrade<br />
</pre><br />
<br />
*Remove the old packages which are no longer needed:<br />
<pre><br />
apt -y purge cracklib-runtime<br />
apt -y autoremove<br />
</pre><br />
<br />
*Reboot the server to ensure all the updates are applied and you're running the new kernel:<br />
<pre><br />
shutdown -r now<br />
</pre><br />
<br />
*Reconnect to the server as <code>root</code> (or <code>sympl</code>, and then swap to root as before)<br />
*Ensure Debian reports the correct version (Release 12):<br />
<br />
lsb_release -a<br />
<br />
*Make sure you're running the new kernel (6.x):<br />
<br />
uname -r<br />
<br />
*Check Sympl was upgraded okay (all versions should start '12.x'):<br />
<br />
dpkg -l 'sympl-*'<br />
<br />
==Finalising==<br />
<br />
You should now check all sites look as expected and make any changes needed for the new PHP version. If you put any sites into maintenance mode then - once you're happy they're operating normally - you can put them back to normal.<br />
<br />
==Problems==<br />
<br />
While this has been tested multiple times, if you experience any problems or the upgrade fails you may need to restore the server to it's previous state. You can either restore a snapshot if you have one or reinstall a fresh copy of the previous or new OS and restore the backups.<br />
<br />
If you notice any non-critical issues, please either report them via [https://bugs.sympl.io the issue tracker] or the [https://forum.sympl.io/c/support/ support forum] along with as much information as possible.<br />
<br />
[[Category:How To]]<br />
[[Category:Upgrading]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Upgrading_Sympl&diff=5029Upgrading Sympl2024-02-28T09:15:17Z<p>Kelduum: /* Problems */</p>
<hr />
<div>Upgrading Sympl versions is a little more complicated than a standard [[Debian]] upgrade but has been tested thoroughly with servers using the [https://www.mythic-beasts.com Mythic Beasts] Debian/Sympl images.<br />
<br />
Unfortunately this guide doesn't cover other hosting providers, as there tend to be small differences in packages and configurations between them and you may encounter other prompts during the upgrade.<br />
<br />
Note that this is different the the typical "update" via running <code>sympl update</code>. That will update the Sympl to the most recent versions of each package on the same major version while this "upgrade" is for upgrading Sympl and Debian major versions (e.g. 11 to 12).<br />
<br />
Upgrades of Debian Stretch (Sympl 9) and Raspbian/Raspberry Pi OS are not supported at this time.<br />
<br />
If you have installed any other packages yourself you may be given other prompts and these additional packages may have compatibility problems, but you should be able to find support for these.<br />
<br />
==Assumptions==<br />
This guide makes the following assumptions:<br />
<br />
*You're familiar with SSH and running commands as the <code>root</code> user.<br />
*You're using a Mythic Beasts virtual or dedicated server.<br />
*Sympl was installed either from an image or using the installer.<br />
*If you have installed any other packages yourself, you can answer their upgrade questions.<br />
*All sites are confirmed to be compatible with the new [PHP] and [MariaDB] versions.<br />
*You're prepared for 30-60 minutes downtime on the server while the upgrade takes place. You may wish to put critical sites into a maintenance mode before starting to ensure no changes take place.<br />
*You have read this entire page before you start the upgrade!<br />
<br />
If any of the above ''aren't'' true you can continue but you may run into problems or break the server in unusual ways, and this is '''not a configuration we can support'''.<br />
<br />
==Before starting==<br />
<br />
*As with any major changes you should first ensure that you have full backups separate from the existing server, that they contain all the relevant information and that you can restore from them in the event the process goes wrong. If using the built-in Sympl backups, ensure you have an off-server copy of the full <code>/var/backups</code> directory.<br />
*Apply any pending upgrades for the current setup:<br />
<pre><br />
sudo apt -y update<br />
sudo apt -y upgrade<br />
sudo apt -y dist-upgrade<br />
sudo sympl update<br />
</pre><br />
<br />
*Reboot the server to ensure it is working normally and you have a stable platform for the update:<br />
<pre>shutdown -r now</pre><br />
<br />
*Where possible, put any sites into maintenance mode to ensure no changes are lost.<br />
*Take a final backup before starting the upgrade process. If using Sympl backups, use <code>sudo backup2l -b</code> to make a new backup then ensure you have a fresh copy of the <code>/var/backups</code> directory. You also may want to take a snapshot of the server so you can quickly roll back.<br />
<br />
==Upgrading==<br />
<br />
=== Sympl 10 to Sympl 11===<br />
<br />
This upgrade will move from PHP 7.3 to PHP 7.4, and replace [[Webalizer]] (which produces web traffic stats) with [[AWFfull]] - the format of the web traffic statistics generated are incompatible, so stats will be generated without any history.<br />
<br />
If at any point you experience a problem with the below you should restore from the most recent backup. <br />
<br />
*Log into the server as <code>root</code>, or log in as <code>sympl</code> and use <code>sudo su -</code> to swap to the <code>root</code> user.<br />
*Replace the current apt sources for Sympl to point to buster:<br />
<pre><br />
sed 's|buster|bullseye|g' /etc/apt/sources.list.d/sympl_buster.list > /etc/apt/sources.list.d/sympl_bullseye.list && rm /etc/apt/sources.list.d/sympl_buster.list<br />
</pre><br />
<br />
*Move the existing sources.list for Debian out of the way:<br />
<pre><br />
mv /etc/apt/sources.list /etc/apt/sources.list_buster_$( date +%s )<br />
</pre><br />
<br />
*Create a new sources list for bullseye:<br />
<pre><br />
echo "deb http://mirror.mythic-beasts.com/debian/ bullseye main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bullseye main<br />
<br />
deb http://security.debian.org/debian-security bullseye-security main<br />
deb-src http://security.debian.org/debian-security bullseye-security main<br />
<br />
deb http://mirror.mythic-beasts.com/debian/ bullseye-updates main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bullseye-updates main" > /etc/apt/sources.list<br />
</pre><br />
<br />
*Check there will be enough disk space to download the updates:<br />
<pre><br />
apt update<br />
apt -o APT::Get::Trivial-Only=true full-upgrade<br />
</pre><br />
<br />
*If there is a warning about not having enough disk space for the upgrade then stop immediately and either free up space or expand the disk before re-running the above command.<br />
*Downtime will begin here, and you must complete the process in one go.<br />
*Install the package updates that can be installed without installing anything new:<br />
<pre><br />
apt -y upgrade --without-new-pkgs<br />
</pre><br />
<br />
*When prompted, answer '''yes''' to restart services without asking.<br />
*Upgrade all other packages:<br />
<pre><br />
apt -y full-upgrade<br />
</pre><br />
<br />
*When prompted, answer '''yes''' to upgrade the RoundCube database.<br />
*When prompted, answer that you want to keep the existing modified RoundCube configuration file.<br />
*Update the remaining dependencies:<br />
<pre><br />
apt -y install guile-2.2-libs --only-upgrade<br />
</pre><br />
<br />
*Remove the old packages which are no longer needed:<br />
<pre><br />
apt -y autoremove<br />
</pre><br />
<br />
*Update the MariaDB service files to Sympl can interact with them:<br />
<pre><br />
systemctl disable mysql.service<br />
systemctl enable mysql.service<br />
</pre><br />
<br />
*Reconfigure the Pure-FTPd authentication for Sympl:<br />
<pre><br />
rm /etc/pure-ftpd/auth/*<br />
ln -s ../conf/ExtAuth /etc/pure-ftpd/auth/60Ext <br />
</pre><br />
<br />
*Move the old web stats out of the way so new ones can be generated:<br />
<pre><br />
find /srv/*/config -maxdepth 1 -mindepth 1 -name 'stats' | sed 's|/config/stats||' | while read dir; do if [ -d "$dir/public/htdocs/stats" ]; then mv -v "$dir/public/htdocs/stats" "$dir/public/stats_sympl10" ; mkdir "$dir/public/htdocs/stats" ; fi ; done<br />
</pre><br />
<br />
*Reboot the server to ensure all the updates are applied and you're running the new kernel:<br />
<pre><br />
shutdown -r now<br />
</pre><br />
<br />
*Reconnect to the server as <code>root</code> (or <code>sympl</code>, and then swap to root as before)<br />
*Ensure Debian reports the correct version (Release 11):<br />
<br />
lsb_release -a<br />
<br />
*Make sure you're running the new kernel (5.x):<br />
<br />
uname -r<br />
<br />
*Check Sympl was upgraded okay (all versions should start '11.x'):<br />
<br />
dpkg -l 'sympl-*'<br />
<br />
===Sympl 11 to Sympl 12===<br />
<br />
This upgrade will move from PHP 7.4 to PHP 8.2 by default, but with a great deal of new PHP configuration options, allowing you to run a site under various PHP versions.<br />
<br />
If at any point you experience a problem with the below you should restore from the most recent backup. <br />
<br />
*Log into the server as <code>root</code>, or log in as <code>sympl</code> and use <code>sudo su -</code> to swap to the <code>root</code> user.<br />
<br />
* Disable the old Sympl repo<br />
<pre>sed -i 's|^deb.*|#&|' /etc/apt/sources.list.d/sympl_bullseye.list<br />
mv /etc/apt/sources.list.d/sympl_bullseye.list /etc/apt/sources.list.d/disabled-$( date +%s )_sympl_bullseye.list<br />
</pre><br />
<br />
* Disable other old Repos for Debian Bullseye<br />
<pre><br />
sed -i 's|^deb http://packages.mythic-beasts.com/mythic/.*|#&|' /etc/apt/sources.list.d/*.list<br />
sed -i 's|^deb .* bullseye .*|#&|' /etc/apt/sources.list.d/*.list<br />
</pre><br />
<br />
* Add the new Apt Repository for Sympl 12 and add the key.<br />
<pre><br />
echo "deb http://packages.mythic-beasts.com/mythic/ bookworm main" > /etc/apt/sources.list.d/sympl_bookworm.list<br />
wget -q https://mirror.mythic-beasts.com/mythic/support@mythic-beasts.com.gpg.key -O /etc/apt/trusted.gpg.d/support@mythic-beasts.com.asc<br />
</pre><br />
<br />
*Move the existing sources.list for Debian out of the way:<br />
<pre><br />
mv /etc/apt/sources.list /etc/apt/sources.list_bullseye_$( date +%s )<br />
</pre><br />
<br />
*Create a new sources list for bullseye:<br />
<pre><br />
echo "deb http://mirror.mythic-beasts.com/debian/ bookworm main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bookworm main<br />
<br />
deb http://security.debian.org/debian-security bookworm-security main<br />
deb-src http://security.debian.org/debian-security bookworm-security main<br />
<br />
deb http://mirror.mythic-beasts.com/debian/ bookworm-updates main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bookworm-updates main" > /etc/apt/sources.list<br />
</pre><br />
<br />
*Set some options for updates:<br />
<pre><br />
export DEBIAN_FRONTEND=noninteractive <br />
export UCF_FORCE_CONFFNEW=YES<br />
</pre><br />
<br />
*Check there will be enough disk space to download the updates:<br />
<pre><br />
apt update<br />
apt -qq -o APT::Get::Trivial-Only=true full-upgrade 2>&1 | tail -n 3 | grep -v 'Trivial Only'<br />
</pre><br />
<br />
*If there is a warning about not having enough disk space for the upgrade then stop immediately and either free up space or expand the disk before re-running the above command.<br />
*Downtime will begin here, and you must now complete the remainder of this process in one go.<br />
*Install the package updates that can be installed without installing anything new:<br />
<pre><br />
apt -y upgrade --without-new-pkgs<br />
</pre><br />
<br />
*If prompted, answer '''yes''' to restart services without asking.<br />
*Disable the old PHP Apache Module<br />
<pre>a2dismod php7.4</pre><br />
*Upgrade all other packages:<br />
<pre><br />
apt -o Dpkg::Options::="--force-confnew" -y full-upgrade<br />
</pre><br />
<br />
*Remove the old packages which are no longer needed:<br />
<pre><br />
apt -y purge cracklib-runtime<br />
apt -y autoremove<br />
</pre><br />
<br />
*Reboot the server to ensure all the updates are applied and you're running the new kernel:<br />
<pre><br />
shutdown -r now<br />
</pre><br />
<br />
*Reconnect to the server as <code>root</code> (or <code>sympl</code>, and then swap to root as before)<br />
*Ensure Debian reports the correct version (Release 12):<br />
<br />
lsb_release -a<br />
<br />
*Make sure you're running the new kernel (6.x):<br />
<br />
uname -r<br />
<br />
*Check Sympl was upgraded okay (all versions should start '12.x'):<br />
<br />
dpkg -l 'sympl-*'<br />
<br />
==Finalising==<br />
<br />
You should now check all sites look as expected and make any changes needed for the new PHP version. If you put any sites into maintenance mode then - once you're happy they're operating normally - you can put them back to normal.<br />
<br />
==Problems==<br />
<br />
While this has been tested multiple times, if you experience any problems or the upgrade fails you may need to restore the server to it's previous state. You can either restore a snapshot if you have one or reinstall a fresh copy of the previous or new OS and restore the backups.<br />
<br />
If you notice any non-critical issues, please either report them via [https://bugs.sympl.io https://bugs.sympl.io] or the [https://forum.sympl.io/c/support/ support forum] along with as much information as possible.<br />
<br />
[[Category:How To]]<br />
[[Category:Upgrading]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Upgrading_Sympl&diff=5028Upgrading Sympl2024-02-28T09:13:27Z<p>Kelduum: </p>
<hr />
<div>Upgrading Sympl versions is a little more complicated than a standard [[Debian]] upgrade but has been tested thoroughly with servers using the [https://www.mythic-beasts.com Mythic Beasts] Debian/Sympl images.<br />
<br />
Unfortunately this guide doesn't cover other hosting providers, as there tend to be small differences in packages and configurations between them and you may encounter other prompts during the upgrade.<br />
<br />
Note that this is different the the typical "update" via running <code>sympl update</code>. That will update the Sympl to the most recent versions of each package on the same major version while this "upgrade" is for upgrading Sympl and Debian major versions (e.g. 11 to 12).<br />
<br />
Upgrades of Debian Stretch (Sympl 9) and Raspbian/Raspberry Pi OS are not supported at this time.<br />
<br />
If you have installed any other packages yourself you may be given other prompts and these additional packages may have compatibility problems, but you should be able to find support for these.<br />
<br />
==Assumptions==<br />
This guide makes the following assumptions:<br />
<br />
*You're familiar with SSH and running commands as the <code>root</code> user.<br />
*You're using a Mythic Beasts virtual or dedicated server.<br />
*Sympl was installed either from an image or using the installer.<br />
*If you have installed any other packages yourself, you can answer their upgrade questions.<br />
*All sites are confirmed to be compatible with the new [PHP] and [MariaDB] versions.<br />
*You're prepared for 30-60 minutes downtime on the server while the upgrade takes place. You may wish to put critical sites into a maintenance mode before starting to ensure no changes take place.<br />
*You have read this entire page before you start the upgrade!<br />
<br />
If any of the above ''aren't'' true you can continue but you may run into problems or break the server in unusual ways, and this is '''not a configuration we can support'''.<br />
<br />
==Before starting==<br />
<br />
*As with any major changes you should first ensure that you have full backups separate from the existing server, that they contain all the relevant information and that you can restore from them in the event the process goes wrong. If using the built-in Sympl backups, ensure you have an off-server copy of the full <code>/var/backups</code> directory.<br />
*Apply any pending upgrades for the current setup:<br />
<pre><br />
sudo apt -y update<br />
sudo apt -y upgrade<br />
sudo apt -y dist-upgrade<br />
sudo sympl update<br />
</pre><br />
<br />
*Reboot the server to ensure it is working normally and you have a stable platform for the update:<br />
<pre>shutdown -r now</pre><br />
<br />
*Where possible, put any sites into maintenance mode to ensure no changes are lost.<br />
*Take a final backup before starting the upgrade process. If using Sympl backups, use <code>sudo backup2l -b</code> to make a new backup then ensure you have a fresh copy of the <code>/var/backups</code> directory. You also may want to take a snapshot of the server so you can quickly roll back.<br />
<br />
==Upgrading==<br />
<br />
=== Sympl 10 to Sympl 11===<br />
<br />
This upgrade will move from PHP 7.3 to PHP 7.4, and replace [[Webalizer]] (which produces web traffic stats) with [[AWFfull]] - the format of the web traffic statistics generated are incompatible, so stats will be generated without any history.<br />
<br />
If at any point you experience a problem with the below you should restore from the most recent backup. <br />
<br />
*Log into the server as <code>root</code>, or log in as <code>sympl</code> and use <code>sudo su -</code> to swap to the <code>root</code> user.<br />
*Replace the current apt sources for Sympl to point to buster:<br />
<pre><br />
sed 's|buster|bullseye|g' /etc/apt/sources.list.d/sympl_buster.list > /etc/apt/sources.list.d/sympl_bullseye.list && rm /etc/apt/sources.list.d/sympl_buster.list<br />
</pre><br />
<br />
*Move the existing sources.list for Debian out of the way:<br />
<pre><br />
mv /etc/apt/sources.list /etc/apt/sources.list_buster_$( date +%s )<br />
</pre><br />
<br />
*Create a new sources list for bullseye:<br />
<pre><br />
echo "deb http://mirror.mythic-beasts.com/debian/ bullseye main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bullseye main<br />
<br />
deb http://security.debian.org/debian-security bullseye-security main<br />
deb-src http://security.debian.org/debian-security bullseye-security main<br />
<br />
deb http://mirror.mythic-beasts.com/debian/ bullseye-updates main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bullseye-updates main" > /etc/apt/sources.list<br />
</pre><br />
<br />
*Check there will be enough disk space to download the updates:<br />
<pre><br />
apt update<br />
apt -o APT::Get::Trivial-Only=true full-upgrade<br />
</pre><br />
<br />
*If there is a warning about not having enough disk space for the upgrade then stop immediately and either free up space or expand the disk before re-running the above command.<br />
*Downtime will begin here, and you must complete the process in one go.<br />
*Install the package updates that can be installed without installing anything new:<br />
<pre><br />
apt -y upgrade --without-new-pkgs<br />
</pre><br />
<br />
*When prompted, answer '''yes''' to restart services without asking.<br />
*Upgrade all other packages:<br />
<pre><br />
apt -y full-upgrade<br />
</pre><br />
<br />
*When prompted, answer '''yes''' to upgrade the RoundCube database.<br />
*When prompted, answer that you want to keep the existing modified RoundCube configuration file.<br />
*Update the remaining dependencies:<br />
<pre><br />
apt -y install guile-2.2-libs --only-upgrade<br />
</pre><br />
<br />
*Remove the old packages which are no longer needed:<br />
<pre><br />
apt -y autoremove<br />
</pre><br />
<br />
*Update the MariaDB service files to Sympl can interact with them:<br />
<pre><br />
systemctl disable mysql.service<br />
systemctl enable mysql.service<br />
</pre><br />
<br />
*Reconfigure the Pure-FTPd authentication for Sympl:<br />
<pre><br />
rm /etc/pure-ftpd/auth/*<br />
ln -s ../conf/ExtAuth /etc/pure-ftpd/auth/60Ext <br />
</pre><br />
<br />
*Move the old web stats out of the way so new ones can be generated:<br />
<pre><br />
find /srv/*/config -maxdepth 1 -mindepth 1 -name 'stats' | sed 's|/config/stats||' | while read dir; do if [ -d "$dir/public/htdocs/stats" ]; then mv -v "$dir/public/htdocs/stats" "$dir/public/stats_sympl10" ; mkdir "$dir/public/htdocs/stats" ; fi ; done<br />
</pre><br />
<br />
*Reboot the server to ensure all the updates are applied and you're running the new kernel:<br />
<pre><br />
shutdown -r now<br />
</pre><br />
<br />
*Reconnect to the server as <code>root</code> (or <code>sympl</code>, and then swap to root as before)<br />
*Ensure Debian reports the correct version (Release 11):<br />
<br />
lsb_release -a<br />
<br />
*Make sure you're running the new kernel (5.x):<br />
<br />
uname -r<br />
<br />
*Check Sympl was upgraded okay (all versions should start '11.x'):<br />
<br />
dpkg -l 'sympl-*'<br />
<br />
===Sympl 11 to Sympl 12===<br />
<br />
This upgrade will move from PHP 7.4 to PHP 8.2 by default, but with a great deal of new PHP configuration options, allowing you to run a site under various PHP versions.<br />
<br />
If at any point you experience a problem with the below you should restore from the most recent backup. <br />
<br />
*Log into the server as <code>root</code>, or log in as <code>sympl</code> and use <code>sudo su -</code> to swap to the <code>root</code> user.<br />
<br />
* Disable the old Sympl repo<br />
<pre>sed -i 's|^deb.*|#&|' /etc/apt/sources.list.d/sympl_bullseye.list<br />
mv /etc/apt/sources.list.d/sympl_bullseye.list /etc/apt/sources.list.d/disabled-$( date +%s )_sympl_bullseye.list<br />
</pre><br />
<br />
* Disable other old Repos for Debian Bullseye<br />
<pre><br />
sed -i 's|^deb http://packages.mythic-beasts.com/mythic/.*|#&|' /etc/apt/sources.list.d/*.list<br />
sed -i 's|^deb .* bullseye .*|#&|' /etc/apt/sources.list.d/*.list<br />
</pre><br />
<br />
* Add the new Apt Repository for Sympl 12 and add the key.<br />
<pre><br />
echo "deb http://packages.mythic-beasts.com/mythic/ bookworm main" > /etc/apt/sources.list.d/sympl_bookworm.list<br />
wget -q https://mirror.mythic-beasts.com/mythic/support@mythic-beasts.com.gpg.key -O /etc/apt/trusted.gpg.d/support@mythic-beasts.com.asc<br />
</pre><br />
<br />
*Move the existing sources.list for Debian out of the way:<br />
<pre><br />
mv /etc/apt/sources.list /etc/apt/sources.list_bullseye_$( date +%s )<br />
</pre><br />
<br />
*Create a new sources list for bullseye:<br />
<pre><br />
echo "deb http://mirror.mythic-beasts.com/debian/ bookworm main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bookworm main<br />
<br />
deb http://security.debian.org/debian-security bookworm-security main<br />
deb-src http://security.debian.org/debian-security bookworm-security main<br />
<br />
deb http://mirror.mythic-beasts.com/debian/ bookworm-updates main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bookworm-updates main" > /etc/apt/sources.list<br />
</pre><br />
<br />
*Set some options for updates:<br />
<pre><br />
export DEBIAN_FRONTEND=noninteractive <br />
export UCF_FORCE_CONFFNEW=YES<br />
</pre><br />
<br />
*Check there will be enough disk space to download the updates:<br />
<pre><br />
apt update<br />
apt -qq -o APT::Get::Trivial-Only=true full-upgrade 2>&1 | tail -n 3 | grep -v 'Trivial Only'<br />
</pre><br />
<br />
*If there is a warning about not having enough disk space for the upgrade then stop immediately and either free up space or expand the disk before re-running the above command.<br />
*Downtime will begin here, and you must now complete the remainder of this process in one go.<br />
*Install the package updates that can be installed without installing anything new:<br />
<pre><br />
apt -y upgrade --without-new-pkgs<br />
</pre><br />
<br />
*If prompted, answer '''yes''' to restart services without asking.<br />
*Disable the old PHP Apache Module<br />
<pre>a2dismod php7.4</pre><br />
*Upgrade all other packages:<br />
<pre><br />
apt -o Dpkg::Options::="--force-confnew" -y full-upgrade<br />
</pre><br />
<br />
*Remove the old packages which are no longer needed:<br />
<pre><br />
apt -y purge cracklib-runtime<br />
apt -y autoremove<br />
</pre><br />
<br />
*Reboot the server to ensure all the updates are applied and you're running the new kernel:<br />
<pre><br />
shutdown -r now<br />
</pre><br />
<br />
*Reconnect to the server as <code>root</code> (or <code>sympl</code>, and then swap to root as before)<br />
*Ensure Debian reports the correct version (Release 12):<br />
<br />
lsb_release -a<br />
<br />
*Make sure you're running the new kernel (6.x):<br />
<br />
uname -r<br />
<br />
*Check Sympl was upgraded okay (all versions should start '12.x'):<br />
<br />
dpkg -l 'sympl-*'<br />
<br />
==Finalising==<br />
<br />
You should now check all sites look as expected and make any changes needed for the new PHP version. If you put any sites into maintenance mode then - once you're happy they're operating normally - you can put them back to normal.<br />
<br />
==Problems==<br />
<br />
While this has been tested multiple times, if you experience any problems or the upgrade fails you may need to restore the server to it's previous state. You can either restore a snapshot if you have one or reinstall a fresh copy of the previous or new OS and restore the backups.<br />
<br />
If you notice any non-critical issues, please either report them via [https://bugs.sympl.io] or the [https://forum.sympl.io/c/support/ support forum] along with as much information as possible.<br />
<br />
[[Category:How To]]<br />
[[Category:Upgrading]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Upgrading_Sympl&diff=5027Upgrading Sympl2024-02-28T09:11:41Z<p>Kelduum: /* Sympl 11 to Sympl 12 */</p>
<hr />
<div>Upgrading Sympl versions is a little more complicated than a standard [[Debian]] upgrade but has been tested thoroughly with servers using the [https://www.mythic-beasts.com Mythic Beasts] Debian/Sympl images.<br />
<br />
Unfortunately this guide doesn't cover other hosting providers, as there tend to be small differences in packages and configurations between them and you may encounter other prompts during the upgrade.<br />
<br />
Note that this is different the the typical "update" via running sympl update. That will update the Sympl to the most recent versions of each package on the same major version while this "upgrade" is for upgrading Sympl and Debian major versions (e.g. 10 to 11).<br />
<br />
Upgrades of Debian Stretch (Sympl 9) and Raspbian/Raspberry Pi OS are not supported at this time.<br />
<br />
If you have installed any other packages yourself you may be given other prompts and these additional packages may have compatibility problems, but you should be able to find support for these.<br />
<br />
==Assumptions==<br />
This guide makes the following assumptions:<br />
<br />
*You're familiar with SSH and running commands as the <code>root</code> user.<br />
*You're using a Mythic Beasts virtual or dedicated server.<br />
*Sympl was installed either from an image or using the installer.<br />
*If you have installed any other packages yourself, you can answer their upgrade questions.<br />
*All sites are confirmed to be compatible with the new [PHP] and [MariaDB] versions.<br />
*You're prepared for 30-60 minutes downtime on the server while the upgrade takes place. You may wish to put critical sites into a maintenance mode before starting to ensure no changes take place.<br />
*You have read this entire page before you start the upgrade!<br />
<br />
If any of the above ''aren't'' true you can continue but you may run into problems or break the server in unusual ways, and this is '''not a configuration we can support'''.<br />
<br />
==Before starting==<br />
<br />
*As with any major changes you should first ensure that you have full backups separate from the existing server, that they contain all the relevant information and that you can restore from them in the event the process goes wrong. If using the built-in Sympl backups, ensure you have an off-server copy of the full <code>/var/backups</code> directory.<br />
*Apply any pending upgrades for the current setup:<br />
<pre><br />
sudo apt -y update<br />
sudo apt -y upgrade<br />
sudo apt -y dist-upgrade<br />
sudo sympl update<br />
</pre><br />
<br />
*Reboot the server to ensure it is working normally and you have a stable platform for the update:<br />
<pre>shutdown -r now</pre><br />
<br />
*Where possible, put any sites into maintenance mode to ensure no changes are lost.<br />
*Take a final backup before starting the upgrade process. If using Sympl backups, use <code>sudo backup2l -b</code> to make a new backup then ensure you have a fresh copy of the <code>/var/backups</code> directory. You also may want to take a snapshot of the server so you can quickly roll back.<br />
<br />
==Upgrading==<br />
<br />
=== Sympl 10 to Sympl 11===<br />
<br />
This upgrade will move from PHP 7.3 to PHP 7.4, and replace [[Webalizer]] (which produces web traffic stats) with [[AWFfull]] - the format of the web traffic statistics generated are incompatible, so stats will be generated without any history.<br />
<br />
If at any point you experience a problem with the below you should restore from the most recent backup. <br />
<br />
*Log into the server as <code>root</code>, or log in as <code>sympl</code> and use <code>sudo su -</code> to swap to the <code>root</code> user.<br />
*Replace the current apt sources for Sympl to point to buster:<br />
<pre><br />
sed 's|buster|bullseye|g' /etc/apt/sources.list.d/sympl_buster.list > /etc/apt/sources.list.d/sympl_bullseye.list && rm /etc/apt/sources.list.d/sympl_buster.list<br />
</pre><br />
<br />
*Move the existing sources.list for Debian out of the way:<br />
<pre><br />
mv /etc/apt/sources.list /etc/apt/sources.list_buster_$( date +%s )<br />
</pre><br />
<br />
*Create a new sources list for bullseye:<br />
<pre><br />
echo "deb http://mirror.mythic-beasts.com/debian/ bullseye main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bullseye main<br />
<br />
deb http://security.debian.org/debian-security bullseye-security main<br />
deb-src http://security.debian.org/debian-security bullseye-security main<br />
<br />
deb http://mirror.mythic-beasts.com/debian/ bullseye-updates main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bullseye-updates main" > /etc/apt/sources.list<br />
</pre><br />
<br />
*Check there will be enough disk space to download the updates:<br />
<pre><br />
apt update<br />
apt -o APT::Get::Trivial-Only=true full-upgrade<br />
</pre><br />
<br />
*If there is a warning about not having enough disk space for the upgrade then stop immediately and either free up space or expand the disk before re-running the above command.<br />
*Downtime will begin here, and you must complete the process in one go.<br />
*Install the package updates that can be installed without installing anything new:<br />
<pre><br />
apt -y upgrade --without-new-pkgs<br />
</pre><br />
<br />
*When prompted, answer '''yes''' to restart services without asking.<br />
*Upgrade all other packages:<br />
<pre><br />
apt -y full-upgrade<br />
</pre><br />
<br />
*When prompted, answer '''yes''' to upgrade the RoundCube database.<br />
*When prompted, answer that you want to keep the existing modified RoundCube configuration file.<br />
*Update the remaining dependencies:<br />
<pre><br />
apt -y install guile-2.2-libs --only-upgrade<br />
</pre><br />
<br />
*Remove the old packages which are no longer needed:<br />
<pre><br />
apt -y autoremove<br />
</pre><br />
<br />
*Update the MariaDB service files to Sympl can interact with them:<br />
<pre><br />
systemctl disable mysql.service<br />
systemctl enable mysql.service<br />
</pre><br />
<br />
*Reconfigure the Pure-FTPd authentication for Sympl:<br />
<pre><br />
rm /etc/pure-ftpd/auth/*<br />
ln -s ../conf/ExtAuth /etc/pure-ftpd/auth/60Ext <br />
</pre><br />
<br />
*Move the old web stats out of the way so new ones can be generated:<br />
<pre><br />
find /srv/*/config -maxdepth 1 -mindepth 1 -name 'stats' | sed 's|/config/stats||' | while read dir; do if [ -d "$dir/public/htdocs/stats" ]; then mv -v "$dir/public/htdocs/stats" "$dir/public/stats_sympl10" ; mkdir "$dir/public/htdocs/stats" ; fi ; done<br />
</pre><br />
<br />
*Reboot the server to ensure all the updates are applied and you're running the new kernel:<br />
<pre><br />
shutdown -r now<br />
</pre><br />
<br />
*Reconnect to the server as <code>root</code> (or <code>sympl</code>, and then swap to root as before)<br />
*Ensure Debian reports the correct version (Release 11):<br />
<br />
lsb_release -a<br />
<br />
*Make sure you're running the new kernel (5.x):<br />
<br />
uname -r<br />
<br />
*Check Sympl was upgraded okay (all versions should start '11.x'):<br />
<br />
dpkg -l 'sympl-*'<br />
<br />
===Sympl 11 to Sympl 12===<br />
<br />
This upgrade will move from PHP 7.4 to PHP 8.2 by default, but with a great deal of new PHP configuration options, allowing you to run a site under various PHP versions.<br />
<br />
If at any point you experience a problem with the below you should restore from the most recent backup. <br />
<br />
*Log into the server as <code>root</code>, or log in as <code>sympl</code> and use <code>sudo su -</code> to swap to the <code>root</code> user.<br />
<br />
* Disable the old Sympl repo<br />
<pre>sed -i 's|^deb.*|#&|' /etc/apt/sources.list.d/sympl_bullseye.list<br />
mv /etc/apt/sources.list.d/sympl_bullseye.list /etc/apt/sources.list.d/disabled-$( date +%s )_sympl_bullseye.list<br />
</pre><br />
<br />
* Disable other old Repos for Debian Bullseye<br />
<pre><br />
sed -i 's|^deb http://packages.mythic-beasts.com/mythic/.*|#&|' /etc/apt/sources.list.d/*.list<br />
sed -i 's|^deb .* bullseye .*|#&|' /etc/apt/sources.list.d/*.list<br />
</pre><br />
<br />
* Add the new Apt Repository for Sympl 12 and add the key.<br />
<pre><br />
echo "deb http://packages.mythic-beasts.com/mythic/ bookworm main" > /etc/apt/sources.list.d/sympl_bookworm.list<br />
wget -q https://mirror.mythic-beasts.com/mythic/support@mythic-beasts.com.gpg.key -O /etc/apt/trusted.gpg.d/support@mythic-beasts.com.asc<br />
</pre><br />
<br />
*Move the existing sources.list for Debian out of the way:<br />
<pre><br />
mv /etc/apt/sources.list /etc/apt/sources.list_bullseye_$( date +%s )<br />
</pre><br />
<br />
*Create a new sources list for bullseye:<br />
<pre><br />
echo "deb http://mirror.mythic-beasts.com/debian/ bookworm main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bookworm main<br />
<br />
deb http://security.debian.org/debian-security bookworm-security main<br />
deb-src http://security.debian.org/debian-security bookworm-security main<br />
<br />
deb http://mirror.mythic-beasts.com/debian/ bookworm-updates main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bookworm-updates main" > /etc/apt/sources.list<br />
</pre><br />
<br />
*Set some options for updates:<br />
<pre><br />
export DEBIAN_FRONTEND=noninteractive <br />
export UCF_FORCE_CONFFNEW=YES<br />
</pre><br />
<br />
*Check there will be enough disk space to download the updates:<br />
<pre><br />
apt update<br />
apt -qq -o APT::Get::Trivial-Only=true full-upgrade 2>&1 | tail -n 3 | grep -v 'Trivial Only'<br />
</pre><br />
<br />
*If there is a warning about not having enough disk space for the upgrade then stop immediately and either free up space or expand the disk before re-running the above command.<br />
*Downtime will begin here, and you must now complete the remainder of this process in one go.<br />
*Install the package updates that can be installed without installing anything new:<br />
<pre><br />
apt -y upgrade --without-new-pkgs<br />
</pre><br />
<br />
*If prompted, answer '''yes''' to restart services without asking.<br />
*Disable the old PHP Apache Module<br />
<pre>a2dismod php7.4</pre><br />
*Upgrade all other packages:<br />
<pre><br />
apt -o Dpkg::Options::="--force-confnew" -y full-upgrade<br />
</pre><br />
<br />
*Remove the old packages which are no longer needed:<br />
<pre><br />
apt -y purge cracklib-runtime<br />
apt -y autoremove<br />
</pre><br />
<br />
*Reboot the server to ensure all the updates are applied and you're running the new kernel:<br />
<pre><br />
shutdown -r now<br />
</pre><br />
<br />
*Reconnect to the server as <code>root</code> (or <code>sympl</code>, and then swap to root as before)<br />
*Ensure Debian reports the correct version (Release 12):<br />
<br />
lsb_release -a<br />
<br />
*Make sure you're running the new kernel (6.x):<br />
<br />
uname -r<br />
<br />
*Check Sympl was upgraded okay (all versions should start '12.x'):<br />
<br />
dpkg -l 'sympl-*'<br />
<br />
==Finalising==<br />
<br />
You should now check all sites look as expected and make any changes needed for the new PHP version. If you put any sites into maintenance mode then - once you're happy they're operating normally - you can put them back to normal.<br />
<br />
==Problems==<br />
<br />
While this has been tested multiple times, if you experience any problems or the upgrade fails you may need to restore the server to it's previous state. You can either restore a snapshot if you have one or reinstall a fresh copy of the previous or new OS and restore the backups.<br />
<br />
If you notice any non-critical issues, please either report them via [https://bugs.sympl.io] or the [https://forum.sympl.io/c/support/ support forum] along with as much information as possible.<br />
<br />
[[Category:How To]]<br />
[[Category:Upgrading]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Upgrading_Sympl&diff=5026Upgrading Sympl2024-02-28T09:10:53Z<p>Kelduum: /* Sympl 11 to Sympl 12 */</p>
<hr />
<div>Upgrading Sympl versions is a little more complicated than a standard [[Debian]] upgrade but has been tested thoroughly with servers using the [https://www.mythic-beasts.com Mythic Beasts] Debian/Sympl images.<br />
<br />
Unfortunately this guide doesn't cover other hosting providers, as there tend to be small differences in packages and configurations between them and you may encounter other prompts during the upgrade.<br />
<br />
Note that this is different the the typical "update" via running sympl update. That will update the Sympl to the most recent versions of each package on the same major version while this "upgrade" is for upgrading Sympl and Debian major versions (e.g. 10 to 11).<br />
<br />
Upgrades of Debian Stretch (Sympl 9) and Raspbian/Raspberry Pi OS are not supported at this time.<br />
<br />
If you have installed any other packages yourself you may be given other prompts and these additional packages may have compatibility problems, but you should be able to find support for these.<br />
<br />
==Assumptions==<br />
This guide makes the following assumptions:<br />
<br />
*You're familiar with SSH and running commands as the <code>root</code> user.<br />
*You're using a Mythic Beasts virtual or dedicated server.<br />
*Sympl was installed either from an image or using the installer.<br />
*If you have installed any other packages yourself, you can answer their upgrade questions.<br />
*All sites are confirmed to be compatible with the new [PHP] and [MariaDB] versions.<br />
*You're prepared for 30-60 minutes downtime on the server while the upgrade takes place. You may wish to put critical sites into a maintenance mode before starting to ensure no changes take place.<br />
*You have read this entire page before you start the upgrade!<br />
<br />
If any of the above ''aren't'' true you can continue but you may run into problems or break the server in unusual ways, and this is '''not a configuration we can support'''.<br />
<br />
==Before starting==<br />
<br />
*As with any major changes you should first ensure that you have full backups separate from the existing server, that they contain all the relevant information and that you can restore from them in the event the process goes wrong. If using the built-in Sympl backups, ensure you have an off-server copy of the full <code>/var/backups</code> directory.<br />
*Apply any pending upgrades for the current setup:<br />
<pre><br />
sudo apt -y update<br />
sudo apt -y upgrade<br />
sudo apt -y dist-upgrade<br />
sudo sympl update<br />
</pre><br />
<br />
*Reboot the server to ensure it is working normally and you have a stable platform for the update:<br />
<pre>shutdown -r now</pre><br />
<br />
*Where possible, put any sites into maintenance mode to ensure no changes are lost.<br />
*Take a final backup before starting the upgrade process. If using Sympl backups, use <code>sudo backup2l -b</code> to make a new backup then ensure you have a fresh copy of the <code>/var/backups</code> directory. You also may want to take a snapshot of the server so you can quickly roll back.<br />
<br />
==Upgrading==<br />
<br />
=== Sympl 10 to Sympl 11===<br />
<br />
This upgrade will move from PHP 7.3 to PHP 7.4, and replace [[Webalizer]] (which produces web traffic stats) with [[AWFfull]] - the format of the web traffic statistics generated are incompatible, so stats will be generated without any history.<br />
<br />
If at any point you experience a problem with the below you should restore from the most recent backup. <br />
<br />
*Log into the server as <code>root</code>, or log in as <code>sympl</code> and use <code>sudo su -</code> to swap to the <code>root</code> user.<br />
*Replace the current apt sources for Sympl to point to buster:<br />
<pre><br />
sed 's|buster|bullseye|g' /etc/apt/sources.list.d/sympl_buster.list > /etc/apt/sources.list.d/sympl_bullseye.list && rm /etc/apt/sources.list.d/sympl_buster.list<br />
</pre><br />
<br />
*Move the existing sources.list for Debian out of the way:<br />
<pre><br />
mv /etc/apt/sources.list /etc/apt/sources.list_buster_$( date +%s )<br />
</pre><br />
<br />
*Create a new sources list for bullseye:<br />
<pre><br />
echo "deb http://mirror.mythic-beasts.com/debian/ bullseye main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bullseye main<br />
<br />
deb http://security.debian.org/debian-security bullseye-security main<br />
deb-src http://security.debian.org/debian-security bullseye-security main<br />
<br />
deb http://mirror.mythic-beasts.com/debian/ bullseye-updates main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bullseye-updates main" > /etc/apt/sources.list<br />
</pre><br />
<br />
*Check there will be enough disk space to download the updates:<br />
<pre><br />
apt update<br />
apt -o APT::Get::Trivial-Only=true full-upgrade<br />
</pre><br />
<br />
*If there is a warning about not having enough disk space for the upgrade then stop immediately and either free up space or expand the disk before re-running the above command.<br />
*Downtime will begin here, and you must complete the process in one go.<br />
*Install the package updates that can be installed without installing anything new:<br />
<pre><br />
apt -y upgrade --without-new-pkgs<br />
</pre><br />
<br />
*When prompted, answer '''yes''' to restart services without asking.<br />
*Upgrade all other packages:<br />
<pre><br />
apt -y full-upgrade<br />
</pre><br />
<br />
*When prompted, answer '''yes''' to upgrade the RoundCube database.<br />
*When prompted, answer that you want to keep the existing modified RoundCube configuration file.<br />
*Update the remaining dependencies:<br />
<pre><br />
apt -y install guile-2.2-libs --only-upgrade<br />
</pre><br />
<br />
*Remove the old packages which are no longer needed:<br />
<pre><br />
apt -y autoremove<br />
</pre><br />
<br />
*Update the MariaDB service files to Sympl can interact with them:<br />
<pre><br />
systemctl disable mysql.service<br />
systemctl enable mysql.service<br />
</pre><br />
<br />
*Reconfigure the Pure-FTPd authentication for Sympl:<br />
<pre><br />
rm /etc/pure-ftpd/auth/*<br />
ln -s ../conf/ExtAuth /etc/pure-ftpd/auth/60Ext <br />
</pre><br />
<br />
*Move the old web stats out of the way so new ones can be generated:<br />
<pre><br />
find /srv/*/config -maxdepth 1 -mindepth 1 -name 'stats' | sed 's|/config/stats||' | while read dir; do if [ -d "$dir/public/htdocs/stats" ]; then mv -v "$dir/public/htdocs/stats" "$dir/public/stats_sympl10" ; mkdir "$dir/public/htdocs/stats" ; fi ; done<br />
</pre><br />
<br />
*Reboot the server to ensure all the updates are applied and you're running the new kernel:<br />
<pre><br />
shutdown -r now<br />
</pre><br />
<br />
*Reconnect to the server as <code>root</code> (or <code>sympl</code>, and then swap to root as before)<br />
*Ensure Debian reports the correct version (Release 11):<br />
<br />
lsb_release -a<br />
<br />
*Make sure you're running the new kernel (5.x):<br />
<br />
uname -r<br />
<br />
*Check Sympl was upgraded okay (all versions should start '11.x'):<br />
<br />
dpkg -l 'sympl-*'<br />
<br />
===Sympl 11 to Sympl 12===<br />
<br />
This upgrade will move from PHP 7.4 to PHP 8.2 by default, but with a great deal of new PHP configuration options, allowing you to run a site under various PHP versions.<br />
<br />
If at any point you experience a problem with the below you should restore from the most recent backup. <br />
<br />
*Log into the server as <code>root</code>, or log in as <code>sympl</code> and use <code>sudo su -</code> to swap to the <code>root</code> user.<br />
<br />
* Disable the old Sympl repo<br />
<pre>sed -i 's|^deb.*|#&|' /etc/apt/sources.list.d/sympl_bullseye.list<br />
mv /etc/apt/sources.list.d/sympl_bullseye.list /etc/apt/sources.list.d/disabled-$( date +%s )_sympl_bullseye.list<br />
</pre><br />
<br />
* Disable other old Repos for Debian Bullseye<br />
<pre><br />
sed -i 's|^deb http://packages.mythic-beasts.com/mythic/.*|#&|' /etc/apt/sources.list.d/*.list<br />
sed -i 's|^deb .* bullseye .*|#&|' /etc/apt/sources.list.d/*.list<br />
</pre><br />
<br />
* Add the new Apt Repository for Sympl 12 and add the key.<br />
<pre><br />
echo "deb http://packages.mythic-beasts.com/mythic/ bookworm main" > /etc/apt/sources.list.d/sympl_bookworm.list<br />
wget -q https://mirror.mythic-beasts.com/mythic/support@mythic-beasts.com.gpg.key -O /etc/apt/trusted.gpg.d/support@mythic-beasts.com.asc<br />
</pre><br />
<br />
*Move the existing sources.list for Debian out of the way:<br />
<pre><br />
mv /etc/apt/sources.list /etc/apt/sources.list_bullseye_$( date +%s )<br />
</pre><br />
<br />
*Create a new sources list for bullseye:<br />
<pre><br />
echo "deb http://mirror.mythic-beasts.com/debian/ bookworm main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bookworm main<br />
<br />
deb http://security.debian.org/debian-security bookworm-security main<br />
deb-src http://security.debian.org/debian-security bookworm-security main<br />
<br />
deb http://mirror.mythic-beasts.com/debian/ bookworm-updates main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bookworm-updates main" > /etc/apt/sources.list<br />
</pre><br />
<br />
*Set some options for updates:<br />
<pre><br />
export DEBIAN_FRONTEND=noninteractive <br />
export UCF_FORCE_CONFFNEW=YES<br />
</pre><br />
<br />
*Check there will be enough disk space to download the updates:<br />
<pre><br />
apt update<br />
apt -qq -o APT::Get::Trivial-Only=true full-upgrade 2>&1 | tail -n 3 | grep -v 'Trivial Only'<br />
</pre><br />
<br />
*If there is a warning about not having enough disk space for the upgrade then stop immediately and either free up space or expand the disk before re-running the above command.<br />
*Downtime will begin here, and you must now complete this process in one go.<br />
*Install the package updates that can be installed without installing anything new:<br />
<pre><br />
apt -y upgrade --without-new-pkgs<br />
</pre><br />
<br />
*If prompted, answer '''yes''' to restart services without asking.<br />
*Disable the old PHP Apache Module<br />
a2dismod php7.4<br />
*Upgrade all other packages:<br />
<pre><br />
apt -o Dpkg::Options::="--force-confnew" -y full-upgrade<br />
</pre><br />
<br />
*Remove the old packages which are no longer needed:<br />
<pre><br />
apt -y purge cracklib-runtime<br />
apt -y autoremove<br />
</pre><br />
<br />
*Reboot the server to ensure all the updates are applied and you're running the new kernel:<br />
<pre><br />
shutdown -r now<br />
</pre><br />
<br />
*Reconnect to the server as <code>root</code> (or <code>sympl</code>, and then swap to root as before)<br />
*Ensure Debian reports the correct version (Release 12):<br />
<br />
lsb_release -a<br />
<br />
*Make sure you're running the new kernel (6.x):<br />
<br />
uname -r<br />
<br />
*Check Sympl was upgraded okay (all versions should start '12.x'):<br />
<br />
dpkg -l 'sympl-*'<br />
<br />
==Finalising==<br />
<br />
You should now check all sites look as expected and make any changes needed for the new PHP version. If you put any sites into maintenance mode then - once you're happy they're operating normally - you can put them back to normal.<br />
<br />
==Problems==<br />
<br />
While this has been tested multiple times, if you experience any problems or the upgrade fails you may need to restore the server to it's previous state. You can either restore a snapshot if you have one or reinstall a fresh copy of the previous or new OS and restore the backups.<br />
<br />
If you notice any non-critical issues, please either report them via [https://bugs.sympl.io] or the [https://forum.sympl.io/c/support/ support forum] along with as much information as possible.<br />
<br />
[[Category:How To]]<br />
[[Category:Upgrading]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Upgrading_Sympl&diff=5025Upgrading Sympl2024-02-28T09:03:13Z<p>Kelduum: /* Upgrading Sympl 10 to Sympl 11 */</p>
<hr />
<div>Upgrading Sympl versions is a little more complicated than a standard [[Debian]] upgrade but has been tested thoroughly with servers using the [https://www.mythic-beasts.com Mythic Beasts] Debian/Sympl images.<br />
<br />
Unfortunately this guide doesn't cover other hosting providers, as there tend to be small differences in packages and configurations between them and you may encounter other prompts during the upgrade.<br />
<br />
Note that this is different the the typical "update" via running sympl update. That will update the Sympl to the most recent versions of each package on the same major version while this "upgrade" is for upgrading Sympl and Debian major versions (e.g. 10 to 11).<br />
<br />
Upgrades of Debian Stretch (Sympl 9) and Raspbian/Raspberry Pi OS are not supported at this time.<br />
<br />
If you have installed any other packages yourself you may be given other prompts and these additional packages may have compatibility problems, but you should be able to find support for these.<br />
<br />
==Assumptions==<br />
This guide makes the following assumptions:<br />
<br />
*You're familiar with SSH and running commands as the <code>root</code> user.<br />
*You're using a Mythic Beasts virtual or dedicated server.<br />
*Sympl was installed either from an image or using the installer.<br />
*If you have installed any other packages yourself, you can answer their upgrade questions.<br />
*All sites are confirmed to be compatible with the new [PHP] and [MariaDB] versions.<br />
*You're prepared for 30-60 minutes downtime on the server while the upgrade takes place. You may wish to put critical sites into a maintenance mode before starting to ensure no changes take place.<br />
*You have read this entire page before you start the upgrade!<br />
<br />
If any of the above ''aren't'' true you can continue but you may run into problems or break the server in unusual ways, and this is '''not a configuration we can support'''.<br />
<br />
==Before starting==<br />
<br />
*As with any major changes you should first ensure that you have full backups separate from the existing server, that they contain all the relevant information and that you can restore from them in the event the process goes wrong. If using the built-in Sympl backups, ensure you have an off-server copy of the full <code>/var/backups</code> directory.<br />
*Apply any pending upgrades for the current setup:<br />
<pre><br />
sudo apt -y update<br />
sudo apt -y upgrade<br />
sudo apt -y dist-upgrade<br />
sudo sympl update<br />
</pre><br />
<br />
*Reboot the server to ensure it is working normally and you have a stable platform for the update:<br />
<pre>shutdown -r now</pre><br />
<br />
*Where possible, put any sites into maintenance mode to ensure no changes are lost.<br />
*Take a final backup before starting the upgrade process. If using Sympl backups, use <code>sudo backup2l -b</code> to make a new backup then ensure you have a fresh copy of the <code>/var/backups</code> directory. You also may want to take a snapshot of the server so you can quickly roll back.<br />
<br />
==Upgrading==<br />
<br />
=== Sympl 10 to Sympl 11===<br />
<br />
This upgrade will move from PHP 7.3 to PHP 7.4, and replace [[Webalizer]] (which produces web traffic stats) with [[AWFfull]] - the format of the web traffic statistics generated are incompatible, so stats will be generated without any history.<br />
<br />
If at any point you experience a problem with the below you should restore from the most recent backup. <br />
<br />
*Log into the server as <code>root</code>, or log in as <code>sympl</code> and use <code>sudo su -</code> to swap to the <code>root</code> user.<br />
*Replace the current apt sources for Sympl to point to buster:<br />
<pre><br />
sed 's|buster|bullseye|g' /etc/apt/sources.list.d/sympl_buster.list > /etc/apt/sources.list.d/sympl_bullseye.list && rm /etc/apt/sources.list.d/sympl_buster.list<br />
</pre><br />
<br />
*Move the existing sources.list for Debian out of the way:<br />
<pre><br />
mv /etc/apt/sources.list /etc/apt/sources.list_buster_$( date +%s )<br />
</pre><br />
<br />
*Create a new sources list for bullseye:<br />
<pre><br />
echo "deb http://mirror.mythic-beasts.com/debian/ bullseye main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bullseye main<br />
<br />
deb http://security.debian.org/debian-security bullseye-security main<br />
deb-src http://security.debian.org/debian-security bullseye-security main<br />
<br />
deb http://mirror.mythic-beasts.com/debian/ bullseye-updates main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bullseye-updates main" > /etc/apt/sources.list<br />
</pre><br />
<br />
*Check there will be enough disk space to download the updates:<br />
<pre><br />
apt update<br />
apt -o APT::Get::Trivial-Only=true full-upgrade<br />
</pre><br />
<br />
*If there is a warning about not having enough disk space for the upgrade then stop immediately and either free up space or expand the disk before re-running the above command.<br />
*Downtime will begin here, and you must complete the process in one go.<br />
*Install the package updates that can be installed without installing anything new:<br />
<pre><br />
apt -y upgrade --without-new-pkgs<br />
</pre><br />
<br />
*When prompted, answer '''yes''' to restart services without asking.<br />
*Upgrade all other packages:<br />
<pre><br />
apt -y full-upgrade<br />
</pre><br />
<br />
*When prompted, answer '''yes''' to upgrade the RoundCube database.<br />
*When prompted, answer that you want to keep the existing modified RoundCube configuration file.<br />
*Update the remaining dependencies:<br />
<pre><br />
apt -y install guile-2.2-libs --only-upgrade<br />
</pre><br />
<br />
*Remove the old packages which are no longer needed:<br />
<pre><br />
apt -y autoremove<br />
</pre><br />
<br />
*Update the MariaDB service files to Sympl can interact with them:<br />
<pre><br />
systemctl disable mysql.service<br />
systemctl enable mysql.service<br />
</pre><br />
<br />
*Reconfigure the Pure-FTPd authentication for Sympl:<br />
<pre><br />
rm /etc/pure-ftpd/auth/*<br />
ln -s ../conf/ExtAuth /etc/pure-ftpd/auth/60Ext <br />
</pre><br />
<br />
*Move the old web stats out of the way so new ones can be generated:<br />
<pre><br />
find /srv/*/config -maxdepth 1 -mindepth 1 -name 'stats' | sed 's|/config/stats||' | while read dir; do if [ -d "$dir/public/htdocs/stats" ]; then mv -v "$dir/public/htdocs/stats" "$dir/public/stats_sympl10" ; mkdir "$dir/public/htdocs/stats" ; fi ; done<br />
</pre><br />
<br />
*Reboot the server to ensure all the updates are applied and you're running the new kernel:<br />
<pre><br />
shutdown -r now<br />
</pre><br />
<br />
*Reconnect to the server as <code>root</code> (or <code>sympl</code>, and then swap to root as before)<br />
*Ensure Debian reports the correct version (Release 11):<br />
<br />
lsb_release -a<br />
<br />
*Make sure you're running the new kernel (5.x):<br />
<br />
uname -r<br />
<br />
*Check Sympl was upgraded okay (all versions should start '11.x'):<br />
<br />
dpkg -l 'sympl-*'<br />
<br />
===Sympl 11 to Sympl 12===<br />
<br />
This upgrade will move from PHP 7.4 to PHP 8.2 by default, but with a great deal of new PHP configuration options, allowing you to run a site under various PHP versions.<br />
<br />
If at any point you experience a problem with the below you should restore from the most recent backup. <br />
<br />
*Log into the server as <code>root</code>, or log in as <code>sympl</code> and use <code>sudo su -</code> to swap to the <code>root</code> user.<br />
<br />
*Replace the current apt sources for Sympl to point to buster:<br />
<pre><br />
sed 's|buster|bullseye|g' /etc/apt/sources.list.d/sympl_buster.list > /etc/apt/sources.list.d/sympl_bullseye.list && rm /etc/apt/sources.list.d/sympl_buster.list<br />
</pre><br />
<br />
*Move the existing sources.list for Debian out of the way:<br />
<pre><br />
mv /etc/apt/sources.list /etc/apt/sources.list_buster_$( date +%s )<br />
</pre><br />
<br />
*Create a new sources list for bullseye:<br />
<pre><br />
echo "deb http://mirror.mythic-beasts.com/debian/ bullseye main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bullseye main<br />
<br />
deb http://security.debian.org/debian-security bullseye-security main<br />
deb-src http://security.debian.org/debian-security bullseye-security main<br />
<br />
deb http://mirror.mythic-beasts.com/debian/ bullseye-updates main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bullseye-updates main" > /etc/apt/sources.list<br />
</pre><br />
<br />
*Check there will be enough disk space to download the updates:<br />
<pre><br />
apt update<br />
apt -o APT::Get::Trivial-Only=true full-upgrade<br />
</pre><br />
<br />
*If there is a warning about not having enough disk space for the upgrade then stop immediately and either free up space or expand the disk before re-running the above command.<br />
*Downtime will begin here, and you must complete the process in one go.<br />
*Install the package updates that can be installed without installing anything new:<br />
<pre><br />
apt -y upgrade --without-new-pkgs<br />
</pre><br />
<br />
*When prompted, answer '''yes''' to restart services without asking.<br />
*Upgrade all other packages:<br />
<pre><br />
apt -y full-upgrade<br />
</pre><br />
<br />
*When prompted, answer '''yes''' to upgrade the RoundCube database.<br />
*When prompted, answer that you want to keep the existing modified RoundCube configuration file.<br />
*Update the remaining dependencies:<br />
<pre><br />
apt -y install guile-2.2-libs --only-upgrade<br />
</pre><br />
<br />
*Remove the old packages which are no longer needed:<br />
<pre><br />
apt -y autoremove<br />
</pre><br />
<br />
*Update the MariaDB service files to Sympl can interact with them:<br />
<pre><br />
systemctl disable mysql.service<br />
systemctl enable mysql.service<br />
</pre><br />
<br />
*Reconfigure the Pure-FTPd authentication for Sympl:<br />
<pre><br />
rm /etc/pure-ftpd/auth/*<br />
ln -s ../conf/ExtAuth /etc/pure-ftpd/auth/60Ext <br />
</pre><br />
<br />
*Move the old web stats out of the way so new ones can be generated:<br />
<pre><br />
find /srv/*/config -maxdepth 1 -mindepth 1 -name 'stats' | sed 's|/config/stats||' | while read dir; do if [ -d "$dir/public/htdocs/stats" ]; then mv -v "$dir/public/htdocs/stats" "$dir/public/stats_sympl10" ; mkdir "$dir/public/htdocs/stats" ; fi ; done<br />
</pre><br />
<br />
*Reboot the server to ensure all the updates are applied and you're running the new kernel:<br />
<pre><br />
shutdown -r now<br />
</pre><br />
<br />
*Reconnect to the server as <code>root</code> (or <code>sympl</code>, and then swap to root as before)<br />
*Ensure Debian reports the correct version (Release 11):<br />
<br />
lsb_release -a<br />
<br />
*Make sure you're running the new kernel (5.x):<br />
<br />
uname -r<br />
<br />
*Check Sympl was upgraded okay (all versions should start '11.x'):<br />
<br />
dpkg -l 'sympl-*'<br />
<br />
==Finalising==<br />
<br />
You should now check all sites look as expected and make any changes needed for the new PHP version. If you put any sites into maintenance mode then - once you're happy they're operating normally - you can put them back to normal.<br />
<br />
==Problems==<br />
<br />
While this has been tested multiple times, if you experience any problems or the upgrade fails you may need to restore the server to it's previous state. You can either restore a snapshot if you have one or reinstall a fresh copy of the previous or new OS and restore the backups.<br />
<br />
If you notice any non-critical issues, please either report them via [https://bugs.sympl.io] or the [https://forum.sympl.io/c/support/ support forum] along with as much information as possible.<br />
<br />
[[Category:How To]]<br />
[[Category:Upgrading]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Upgrading_Sympl&diff=5024Upgrading Sympl2024-02-28T09:01:19Z<p>Kelduum: </p>
<hr />
<div>Upgrading Sympl versions is a little more complicated than a standard [[Debian]] upgrade but has been tested thoroughly with servers using the [https://www.mythic-beasts.com Mythic Beasts] Debian/Sympl images.<br />
<br />
Unfortunately this guide doesn't cover other hosting providers, as there tend to be small differences in packages and configurations between them and you may encounter other prompts during the upgrade.<br />
<br />
Note that this is different the the typical "update" via running sympl update. That will update the Sympl to the most recent versions of each package on the same major version while this "upgrade" is for upgrading Sympl and Debian major versions (e.g. 10 to 11).<br />
<br />
Upgrades of Debian Stretch (Sympl 9) and Raspbian/Raspberry Pi OS are not supported at this time.<br />
<br />
If you have installed any other packages yourself you may be given other prompts and these additional packages may have compatibility problems, but you should be able to find support for these.<br />
<br />
==Assumptions==<br />
This guide makes the following assumptions:<br />
<br />
*You're familiar with SSH and running commands as the <code>root</code> user.<br />
*You're using a Mythic Beasts virtual or dedicated server.<br />
*Sympl was installed either from an image or using the installer.<br />
*If you have installed any other packages yourself, you can answer their upgrade questions.<br />
*All sites are confirmed to be compatible with the new [PHP] and [MariaDB] versions.<br />
*You're prepared for 30-60 minutes downtime on the server while the upgrade takes place. You may wish to put critical sites into a maintenance mode before starting to ensure no changes take place.<br />
*You have read this entire page before you start the upgrade!<br />
<br />
If any of the above ''aren't'' true you can continue but you may run into problems or break the server in unusual ways, and this is '''not a configuration we can support'''.<br />
<br />
==Before starting==<br />
<br />
*As with any major changes you should first ensure that you have full backups separate from the existing server, that they contain all the relevant information and that you can restore from them in the event the process goes wrong. If using the built-in Sympl backups, ensure you have an off-server copy of the full <code>/var/backups</code> directory.<br />
*Apply any pending upgrades for the current setup:<br />
<pre><br />
sudo apt -y update<br />
sudo apt -y upgrade<br />
sudo apt -y dist-upgrade<br />
sudo sympl update<br />
</pre><br />
<br />
*Reboot the server to ensure it is working normally and you have a stable platform for the update:<br />
<pre>shutdown -r now</pre><br />
<br />
*Where possible, put any sites into maintenance mode to ensure no changes are lost.<br />
*Take a final backup before starting the upgrade process. If using Sympl backups, use <code>sudo backup2l -b</code> to make a new backup then ensure you have a fresh copy of the <code>/var/backups</code> directory. You also may want to take a snapshot of the server so you can quickly roll back.<br />
<br />
==Upgrading==<br />
<br />
=== Sympl 10 to Sympl 11===<br />
<br />
This upgrade will move from PHP 7.3 to PHP 7.4, and replace [[Webalizer]] (which produces web traffic stats) with [[AWFfull]] - the format of the web traffic statistics generated are incompatible, so stats will be generated without any history.<br />
<br />
If at any point you experience a problem with the below you should restore from the most recent backup. <br />
<br />
*Log into the server as <code>root</code>, or log in as <code>sympl</code> and use <code>sudo su -</code> to swap to the <code>root</code> user.<br />
*Replace the current apt sources for Sympl to point to buster:<br />
<pre><br />
sed 's|buster|bullseye|g' /etc/apt/sources.list.d/sympl_buster.list > /etc/apt/sources.list.d/sympl_bullseye.list && rm /etc/apt/sources.list.d/sympl_buster.list<br />
</pre><br />
<br />
*Move the existing sources.list for Debian out of the way:<br />
<pre><br />
mv /etc/apt/sources.list /etc/apt/sources.list_buster_$( date +%s )<br />
</pre><br />
<br />
*Create a new sources list for bullseye:<br />
<pre><br />
echo "deb http://mirror.mythic-beasts.com/debian/ bullseye main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bullseye main<br />
<br />
deb http://security.debian.org/debian-security bullseye-security main<br />
deb-src http://security.debian.org/debian-security bullseye-security main<br />
<br />
deb http://mirror.mythic-beasts.com/debian/ bullseye-updates main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bullseye-updates main" > /etc/apt/sources.list<br />
</pre><br />
<br />
*Check there will be enough disk space to download the updates:<br />
<pre><br />
apt update<br />
apt -o APT::Get::Trivial-Only=true full-upgrade<br />
</pre><br />
<br />
*If there is a warning about not having enough disk space for the upgrade then stop immediately and either free up space or expand the disk before re-running the above command.<br />
*Downtime will begin here, and you must complete the process in one go.<br />
*Install the package updates that can be installed without installing anything new:<br />
<pre><br />
apt -y upgrade --without-new-pkgs<br />
</pre><br />
<br />
*When prompted, answer '''yes''' to restart services without asking.<br />
*Upgrade all other packages:<br />
<pre><br />
apt -y full-upgrade<br />
</pre><br />
<br />
*When prompted, answer '''yes''' to upgrade the RoundCube database.<br />
*When prompted, answer that you want to keep the existing modified RoundCube configuration file.<br />
*Update the remaining dependencies:<br />
<pre><br />
apt -y install guile-2.2-libs --only-upgrade<br />
</pre><br />
<br />
*Remove the old packages which are no longer needed:<br />
<pre><br />
apt -y autoremove<br />
</pre><br />
<br />
*Update the MariaDB service files to Sympl can interact with them:<br />
<pre><br />
systemctl disable mysql.service<br />
systemctl enable mysql.service<br />
</pre><br />
<br />
*Reconfigure the Pure-FTPd authentication for Sympl:<br />
<pre><br />
rm /etc/pure-ftpd/auth/*<br />
ln -s ../conf/ExtAuth /etc/pure-ftpd/auth/60Ext <br />
</pre><br />
<br />
*Move the old web stats out of the way so new ones can be generated:<br />
<pre><br />
find /srv/*/config -maxdepth 1 -mindepth 1 -name 'stats' | sed 's|/config/stats||' | while read dir; do if [ -d "$dir/public/htdocs/stats" ]; then mv -v "$dir/public/htdocs/stats" "$dir/public/stats_sympl10" ; mkdir "$dir/public/htdocs/stats" ; fi ; done<br />
</pre><br />
<br />
*Reboot the server to ensure all the updates are applied and you're running the new kernel:<br />
<pre><br />
shutdown -r now<br />
</pre><br />
<br />
*Reconnect to the server as <code>root</code> (or <code>sympl</code>, and then swap to root as before)<br />
*Ensure Debian reports the correct version (Release 11):<br />
<br />
lsb_release -a<br />
<br />
*Make sure you're running the new kernel (5.x):<br />
<br />
uname -r<br />
<br />
*Check Sympl was upgraded okay (all versions should start '11.x'):<br />
<br />
dpkg -l 'sympl-*'<br />
<br />
===Upgrading Sympl 10 to Sympl 11===<br />
<br />
This upgrade will move from PHP 7.3 to PHP 7.4, and replace [[Webalizer]] (which produces web traffic stats) with [[AWFfull]] - the format of the web traffic statistics generated are incompatible, so stats will be generated without any history.<br />
<br />
If at any point you experience a problem with the below you should restore from the most recent backup. <br />
<br />
*Log into the server as <code>root</code>, or log in as <code>sympl</code> and use <code>sudo su -</code> to swap to the <code>root</code> user.<br />
*Replace the current apt sources for Sympl to point to buster:<br />
<pre><br />
sed 's|buster|bullseye|g' /etc/apt/sources.list.d/sympl_buster.list > /etc/apt/sources.list.d/sympl_bullseye.list && rm /etc/apt/sources.list.d/sympl_buster.list<br />
</pre><br />
<br />
*Move the existing sources.list for Debian out of the way:<br />
<pre><br />
mv /etc/apt/sources.list /etc/apt/sources.list_buster_$( date +%s )<br />
</pre><br />
<br />
*Create a new sources list for bullseye:<br />
<pre><br />
echo "deb http://mirror.mythic-beasts.com/debian/ bullseye main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bullseye main<br />
<br />
deb http://security.debian.org/debian-security bullseye-security main<br />
deb-src http://security.debian.org/debian-security bullseye-security main<br />
<br />
deb http://mirror.mythic-beasts.com/debian/ bullseye-updates main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bullseye-updates main" > /etc/apt/sources.list<br />
</pre><br />
<br />
*Check there will be enough disk space to download the updates:<br />
<pre><br />
apt update<br />
apt -o APT::Get::Trivial-Only=true full-upgrade<br />
</pre><br />
<br />
*If there is a warning about not having enough disk space for the upgrade then stop immediately and either free up space or expand the disk before re-running the above command.<br />
*Downtime will begin here, and you must complete the process in one go.<br />
*Install the package updates that can be installed without installing anything new:<br />
<pre><br />
apt -y upgrade --without-new-pkgs<br />
</pre><br />
<br />
*When prompted, answer '''yes''' to restart services without asking.<br />
*Upgrade all other packages:<br />
<pre><br />
apt -y full-upgrade<br />
</pre><br />
<br />
*When prompted, answer '''yes''' to upgrade the RoundCube database.<br />
*When prompted, answer that you want to keep the existing modified RoundCube configuration file.<br />
*Update the remaining dependencies:<br />
<pre><br />
apt -y install guile-2.2-libs --only-upgrade<br />
</pre><br />
<br />
*Remove the old packages which are no longer needed:<br />
<pre><br />
apt -y autoremove<br />
</pre><br />
<br />
*Update the MariaDB service files to Sympl can interact with them:<br />
<pre><br />
systemctl disable mysql.service<br />
systemctl enable mysql.service<br />
</pre><br />
<br />
*Reconfigure the Pure-FTPd authentication for Sympl:<br />
<pre><br />
rm /etc/pure-ftpd/auth/*<br />
ln -s ../conf/ExtAuth /etc/pure-ftpd/auth/60Ext <br />
</pre><br />
<br />
*Move the old web stats out of the way so new ones can be generated:<br />
<pre><br />
find /srv/*/config -maxdepth 1 -mindepth 1 -name 'stats' | sed 's|/config/stats||' | while read dir; do if [ -d "$dir/public/htdocs/stats" ]; then mv -v "$dir/public/htdocs/stats" "$dir/public/stats_sympl10" ; mkdir "$dir/public/htdocs/stats" ; fi ; done<br />
</pre><br />
<br />
*Reboot the server to ensure all the updates are applied and you're running the new kernel:<br />
<pre><br />
shutdown -r now<br />
</pre><br />
<br />
*Reconnect to the server as <code>root</code> (or <code>sympl</code>, and then swap to root as before)<br />
*Ensure Debian reports the correct version (Release 11):<br />
<br />
lsb_release -a<br />
<br />
*Make sure you're running the new kernel (5.x):<br />
<br />
uname -r<br />
<br />
*Check Sympl was upgraded okay (all versions should start '11.x'):<br />
<br />
dpkg -l 'sympl-*'<br />
<br />
<br />
==Finalising==<br />
<br />
You should now check all sites look as expected and make any changes needed for the new PHP version. If you put any sites into maintenance mode then - once you're happy they're operating normally - you can put them back to normal.<br />
<br />
==Problems==<br />
<br />
While this has been tested multiple times, if you experience any problems or the upgrade fails you may need to restore the server to it's previous state. You can either restore a snapshot if you have one or reinstall a fresh copy of the previous or new OS and restore the backups.<br />
<br />
If you notice any non-critical issues, please either report them via [https://bugs.sympl.io] or the [https://forum.sympl.io/c/support/ support forum] along with as much information as possible.<br />
<br />
[[Category:How To]]<br />
[[Category:Upgrading]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Installing_Sympl&diff=5023Installing Sympl2023-11-09T20:26:24Z<p>Kelduum: /* Manual Install */</p>
<hr />
<div>There are a few ways of installing Sympl. You will need a [[Debian]] or [[Raspberry Pi OS]] server running Buster (10), Bullseye (11) or Bookworm (12), and root access to the server. We suggest the server is freshly re-imaged, with only minimal packages installed on it and a correctly configured hostname.<br />
<br />
==Imaged Install==<br />
If you're using a virtual server from [https://www.mythic-beasts.com Mythic Beasts], you can use their automatic installer to install Sympl and set most things up for you.<blockquote>See ''[[Installing Sympl on Mythic Beasts]]'' for more information.</blockquote><br />
<br />
==Automatic Install==<br />
There is a basic auto-install script which can be used to install Sympl with minimal intervention and point the user to important resources.<br />
<br />
===Install Stable/Production Version===<br />
<pre>wget https://gitlab.com/sympl.io/install/-/raw/master/install.sh</pre><br />
<pre>bash install.sh</pre><br /><br />
===Install Beta/Testing Version===<br />
<pre>wget https://gitlab.com/sympl.io/install/-/raw/master/install.sh</pre><br />
<pre>bash install.sh --testing</pre><br />
<br />
===Non Interactive Install===<br />
The install script supports a non-interactive install, with the <code>--noninteractive</code> switch.<br />
<br />
This disables the normal 5 second delay before installing.<br />
<br />
If using this in an automated script, please ensure that users are pointed to the URL [https://wiki.sympl.host/Get_Started https://wiki.sympl.io/Get_Started] and are made aware of the file <code>README_SYMPL.txt</code> in the root adn sympl users home directories for documentation, and strongly suggest they update the password for the <code>sympl</code> user as soon as possible.<br />
<br />
==Manual Install==<br />
<br />
Alternatively, you can install manually:<br />
<br />
<pre>apt install wget gnupg</pre><br />
<pre>wget -qO- http://mirror.mythic-beasts.com/mythic/support@mythic-beasts.com.gpg.key | apt-key add -</pre><br />
<pre>echo deb http://packages.mythic-beasts.com/mythic/ $(grep '^VERSION_CODENAME' /etc/os-release | cut -d'=' -f2) main > /etc/apt/sources.list.d/sympl_mythic-beasts.list</pre><br />
<pre>apt-get update</pre><br />
<pre>apt-get install --install-recommends sympl-core</pre><br />
<br />
You will be prompted for a number of things during the install. Depending on the state of your system, some of these may not be asked or may be in another order: <br />
<br />
{| class="wikitable"<br />
|-<br />
!Prompt!!Answer<br />
|-<br />
|Configuring roundcube-core: Configure database for roundcube with dbconfig-common?||<code>Yes</code><br />
|-<br />
|Configuring roundcube-core: Database type to be used by roundcube||<code>MySQL</code><br />
|-<br />
|Configuring roundcube-core: Host running the server for roundcube||<code>localhost</code><br />
|-<br />
|Configuring roundcube-core: Password of the database’s administrative user||Leave Blank<br />
|-<br />
|Configuring roundcube-core: MySQL application password for roundcube||Leave Blank<br />
|-<br />
|User preference (Leave blank to generate a random password)||Leave Blank<br />
|-<br />
|Configuring phpmyadmin: Configure database for phpmyadmin with dbconfig-common?||<code>Yes</code><br />
|-<br />
|Configuring phpmyadmin: Host running the MySQL server for phpmyadmin||<code>localhost</code><br />
|-<br />
|Configuring phpmyadmin: Web server to reconfigure automatically||<code>apache2</code><br />
|-<br />
|Configuring phpmyadmin: Perform upgrade on database for phpmyadmin with dbconfig-common?||<code>yes</code><br />
|-<br />
|Configuring libc6:amd64: Restart services during package upgrades without asking?||<code>Yes</code><br />
|-<br />
|Configuration file /etc/sysctl.conf modified since installation||<code>Install the package maintainer's version</code><br />
|-<br />
|Configuring openssh-server||<code>Install the package maintainer's version</code><br />
|-<br />
|Configuring grub-pc||<code>Keep the local version currently installed</code><br />
|-<br />
|Configuration file /etc/ntp.conf modified since installation||<code>Keep your currently-installed version</code><br />
|-<br />
|Configuration file /etc/phpmyadmin/config.inc.php modified since installation||<code>Install the package maintainer’s version</code><br />
|-<br />
|Configuring unattended-upgrades||<code>Install the package maintainer’s version</code><br />
|}<br />
<br />
Remember to set the new 'sympl' users password with <code>passwd sympl</code> once you have installed.<br />
<br />
[[Category:Installation]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Installing_Sympl&diff=5022Installing Sympl2023-11-02T16:06:43Z<p>Kelduum: </p>
<hr />
<div>There are a few ways of installing Sympl. You will need a [[Debian]] or [[Raspberry Pi OS]] server running Buster (10), Bullseye (11) or Bookworm (12), and root access to the server. We suggest the server is freshly re-imaged, with only minimal packages installed on it and a correctly configured hostname.<br />
<br />
==Imaged Install==<br />
If you're using a virtual server from [https://www.mythic-beasts.com Mythic Beasts], you can use their automatic installer to install Sympl and set most things up for you.<blockquote>See ''[[Installing Sympl on Mythic Beasts]]'' for more information.</blockquote><br />
<br />
==Automatic Install==<br />
There is a basic auto-install script which can be used to install Sympl with minimal intervention and point the user to important resources.<br />
<br />
===Install Stable/Production Version===<br />
<pre>wget https://gitlab.com/sympl.io/install/-/raw/master/install.sh</pre><br />
<pre>bash install.sh</pre><br /><br />
===Install Beta/Testing Version===<br />
<pre>wget https://gitlab.com/sympl.io/install/-/raw/master/install.sh</pre><br />
<pre>bash install.sh --testing</pre><br />
<br />
===Non Interactive Install===<br />
The install script supports a non-interactive install, with the <code>--noninteractive</code> switch.<br />
<br />
This disables the normal 5 second delay before installing.<br />
<br />
If using this in an automated script, please ensure that users are pointed to the URL [https://wiki.sympl.host/Get_Started https://wiki.sympl.io/Get_Started] and are made aware of the file <code>README_SYMPL.txt</code> in the root adn sympl users home directories for documentation, and strongly suggest they update the password for the <code>sympl</code> user as soon as possible.<br />
<br />
==Manual Install==<br />
<br />
Alternatively, you can install manually:<br />
<br />
<pre>wget -qO- http://mirror.mythic-beasts.com/mythic/support@mythic-beasts.com.gpg.key | apt-key add -</pre><br />
<pre>echo deb http://packages.mythic-beasts.com/mythic/ $(grep '^VERSION_CODENAME' /etc/os-release | cut -d'=' -f2) main > /etc/apt/sources.list.d/sympl_mythic-beasts.list</pre><br />
<pre>apt-get update</pre><br />
<pre>apt-get install --install-recommends sympl-core</pre><br />
<br />
You will be prompted for a number of things during the install. Depending on the state of your system, some of these may not be asked or may be in another order: <br />
<br />
{| class="wikitable"<br />
|-<br />
!Prompt!!Answer<br />
|-<br />
|Configuring roundcube-core: Configure database for roundcube with dbconfig-common?||<code>Yes</code><br />
|-<br />
|Configuring roundcube-core: Database type to be used by roundcube||<code>MySQL</code><br />
|-<br />
|Configuring roundcube-core: Host running the server for roundcube||<code>localhost</code><br />
|-<br />
|Configuring roundcube-core: Password of the database’s administrative user||Leave Blank<br />
|-<br />
|Configuring roundcube-core: MySQL application password for roundcube||Leave Blank<br />
|-<br />
|User preference (Leave blank to generate a random password)||Leave Blank<br />
|-<br />
|Configuring phpmyadmin: Configure database for phpmyadmin with dbconfig-common?||<code>Yes</code><br />
|-<br />
|Configuring phpmyadmin: Host running the MySQL server for phpmyadmin||<code>localhost</code><br />
|-<br />
|Configuring phpmyadmin: Web server to reconfigure automatically||<code>apache2</code><br />
|-<br />
|Configuring phpmyadmin: Perform upgrade on database for phpmyadmin with dbconfig-common?||<code>yes</code><br />
|-<br />
|Configuring libc6:amd64: Restart services during package upgrades without asking?||<code>Yes</code><br />
|-<br />
|Configuration file /etc/sysctl.conf modified since installation||<code>Install the package maintainer's version</code><br />
|-<br />
|Configuring openssh-server||<code>Install the package maintainer's version</code><br />
|-<br />
|Configuring grub-pc||<code>Keep the local version currently installed</code><br />
|-<br />
|Configuration file /etc/ntp.conf modified since installation||<code>Keep your currently-installed version</code><br />
|-<br />
|Configuration file /etc/phpmyadmin/config.inc.php modified since installation||<code>Install the package maintainer’s version</code><br />
|-<br />
|Configuring unattended-upgrades||<code>Install the package maintainer’s version</code><br />
|}<br />
<br />
Remember to set the new 'sympl' users password with <code>passwd sympl</code> once you have installed.<br />
<br />
[[Category:Installation]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Contributing&diff=5021Contributing2023-06-13T16:35:24Z<p>Kelduum: </p>
<hr />
<div>The Sympl source is hosted on gitlab.com at [https://gitlab.com/sympl.io/sympl gitlab.com/sympl.io/sympl].<br />
<br />
Contributions to the project as well as documentation here on the wiki are more than welcome.</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Website_Configuration_Reference&diff=5020Website Configuration Reference2023-06-12T18:25:28Z<p>Kelduum: /* Hidden Files */</p>
<hr />
<div>This page is a detailed breakdown of all the configuration options and files available when configuring website hosting on Sympl.<br />
<br />
As with all the other documentation here, the site <code>'''''example.com'''''</code> will used, and you should substitute this for your domain.<br />
<br />
All configuration for this domain will be in the /srv/example.com/ directory.<br />
<br />
Sympl uses the [[Apache]] web server, along with the relevant version of [[PHP]] for your version of [[Debian]], along with the typical PHP extensions. See [[Supported PHP Versions]].<br />
<br />
==Getting Started==<br />
The files for example.com are in the <code>/srv/'''''example.com'''''/public/htdocs</code> directory which is the site root.<br />
<br />
*If this directory doesn't exist, is empty, or has no <code>index.php</code> or <code>index.html</code>, the default page will be served, mentioning there is no content on the site.<br />
*The content in the directory will be served for both www.example.com and example.com, so theres no need to prefix the domain with www.<br />
*If you want to serve different content for www.example.com and example.com, you can create /srv/www.example.com as a separate directory.<br />
*Within an hour of the directory creation, a new configuration will [[Sympl-web-configure|automatically be created]] for Apache.<br />
<br />
More detailed information about how Sympl serves content can be found at ''[[How Web Hosting Works on Sympl]]''.<br />
<br />
==Testing Your Sites==<br />
New sites can be tested before they are made live using the 'testing' domains. If your hosting provider provides a wildcard DNS entry on your server pointing to its hostname (and the [[Default Site|default site]] is set to match), then sites can be accessed via this method.<br />
<br />
You can confirm if this is the case using <code>dig</code> or a similar tool - if your server is named <code>'''''server.example.host'''''</code>, if you run <code>dig +short randomname.'''''server.example.host'''''</code> and get a response with the server's IP address, then this is the case.<br />
<br />
If so, you can access any of the sites via this method in the format <domain_directory>.testing.<server_hostname>, for example <code>'''''example.com'''''.testing.'''''server.example.host'''''</code>. Note that the <code>www.</code> should not be included in this case.<br />
<br />
Note that this only applies to websites (not email, FTP and similar), and will not work fully in all instances, as some sites will redirect to their expected hostname or similar. If this is the case, you can test by [[Editing Your Hosts File|editing your hosts file]] on your local computer.<br />
<br />
== PHP Configuration ==<br />
<br />
PHP is the scripting language which the popular Content Management Systems and most websites is written in. It's very popular due to it's flexibility and ease of use, which means that the development of PHP moves quickly, with new versions released every year or so.<br />
<br />
With PHP development moving quickly, the Debian release cycle being every two years, and the common need to run sites on older versions, it's not uncommon to see an instance where you need a different version of PHP than the one bundled with the operating system.<br />
<br />
=== Selecting a PHP Version ===<br />
This isn't currently possible to do automatically on Sympl 11 and earlier, there are community-supported work-arounds. Sympl 12 adds support for selectable PHP versions, and this functionality is being back-ported to earlier versions.<br />
<br />
{{Template:Sympl 12 Only}}<br />
To select a PHP version for a specific site, place the PHP major and minor versions (such as '5.6', '7.3' or '8.1') in the file <code>config/php</code> and run <code>sudo sympl-php-configure</code>.<br />
<br />
This will then install the relevant PHP version from [https://deb.sury.org https://deb.sury.org] if required, along with the typical PHP packages, and configure the site to use that PHP version. Note there is a small extra disk space requirement for each extra version of PHP installed.<br />
<br />
If other PHP modules/extensions are required for the site, their package names can be placed in <code>config/php-modules</code>, and they will be installed automatically the next time <code>sudo sympl-php-configure</code> is run. Package names are the name of the Debian packaged modules without the PHP version, so the <code>php8.1-tidy</code> package would be listed in the file as <code>tidy</code>. PHP extensions can also be installed manually using apt.<br />
<br />
All sites default to a pool named 'default' unless specified otherwise in <code>config/php-pool</code>. If you require any configuration changes, or wish to adjust resources for a site, you should configure it with it's own pool. Note that each pool has its own memory requirements and PHP instances standing by, so running a large number of pools will consume more RAM on your server.<br />
<br />
=== .htaccess vs .user.ini ===<br />
{{Template:Sympl 12 Only}}<br />
When using the default PHP version (ie: not specifying one) the site will run under the default PHP version for the distribution (ie: PHP 8.2 for Debian Bookworm) using 'mod_apache'. This will parse PHP variables and overrides via the <code>.htaccess</code> file in the web content directory, allowing you to make changes on a per-directory basis.<br />
<br />
Running a site under 'FPM' as the configured sites do means they are only passed the relevant file, so require the same configuration entries in a slightly different format in the file <code>.user.ini</code> file, in the same location as <code>.htaccess</code>.<br />
<br />
If you don't already have a <code>.user.ini</code> file in place, Sympl will automatically create and manage one for you each time <code>sudo sympl-php-configure</code> is run. <br />
<br />
=== PHP Command Line ===<br />
{{Template:Sympl 12 Only}}<br />
In some instances, you may need to run the PHP from the command line but need a version other than the default. To do so, rather than using the plain <code>php example.php</code> command, simply append the version, for example <code>php8.1 example.php</code>.<br />
<br />
=== Extended Configuration ===<br />
{{Template:Sympl 12 Only}}<br />
Sympl supports a number of other extended configuration options, including selectable user and group that the PHP pool should be executed as, with <code>config/php-user</code> and <code>config/php-group</code> respectively. These default to www-data, but if must exist if they are changed, and cannot be system users (ie: with an ID below 1000). Note that these settings also inherit the values of <code>public-user</code> and <code>public-group</code> if set.<br />
<br />
As the PHP pool files are managed automatically by Sympl to ensure that PHP continues running, manual changes to the pool configurations will be overwritten on each run. If a change to a pool configuration is required, extra configuration lines can be added to <code>/etc/sympl/php/<version>/includes.d/<pool_name>.conf</code>. The pool name is defined as <code><pool_name>[_<username>[_<groupname>]]</code> with the username and group being optional if not left on the default.<br />
<br />
===PHP Security===<br />
By default, a number of rules are included in the Apache configuration which limit the access of sites running PHP, preventing a compromised site from accessing content outside the <code>/srv/example.com/public/</code> directory, and setting both a domain-specific temp directory and session directory as <code>/srv/example.com/php_tmp/</code> and <code>/srv/example.com/php_sessions/</code> respectively.<br />
<br />
A default configuration is also in place for the ever-popular [[WordPress]], which prevents PHP files from being accessed or executed from within the upload folder, which tend to be the source of most site compromises.<br />
<br />
These restrictions can be disabled by creating the file <code>/srv/example.com/config/disable-php-security</code>, and running <code>sudo sympl-web-configure</code>.<br />
<br />
====PHP Lockdown====<br />
Also available but not enabled by default is a '[[PHP Lockdown|lockdown]]' configuration, which limits a number of potentially dangerous functions in PHP for ''all sites'' where a PHP version is not selected.<br />
<br />
This can be enabled with the command line...<br />
<br />
'''For Sympl 10.x'''<br />
sudo ln -s /etc/php/7.0/mods-available/sympl-web-lockdown.ini /etc/php/7.0/apache2/conf.d/01-sympl-web-lockdown.ini<br />
sudo service apache2 reload<br />
'''For Sympl 11.x'''<br />
sudo ln -s /etc/php/7.3/mods-available/sympl-web-lockdown.ini /etc/php/7.3/apache2/conf.d/01-sympl-web-lockdown.ini<br />
sudo service apache2 reload<br />
'''For Sympl 12.x'''<br />
sudo ln -s /etc/php/8.2/mods-available/sympl-web-lockdown.ini /etc/php/8.2/apache2/conf.d/01-sympl-web-lockdown.ini<br />
sudo service apache2 reload<br />
<br />
Note that this will significantly restrict PHP access, and will affect all sites on the same server, so you should confirm that all sites work as expected once this has been run.<br />
<br />
==Serving the Same Content on Multiple Domains.==<br />
In some cases you may want to accept traffic for and serve the same content for multiple domains, such as [[WordPress Multi-site|WordPress multi-site]] configurations.<br />
<br />
Both of these assume you have the main site already configured and working.<br />
<br />
===Aliasing the Whole Domain===<br />
The most simple option is to alias the whole domain. This will result in the whole configuration including other services such as email, SSL certificates, and FTP sites all sharing the same domain.<br />
<br />
To do this, you only need to create a [[Symbolic Link|symbolic link]] to the directory of the site you want to alias. Aliasing <code>'''''example.org'''''</code> (new domain) to <code>'''''example.com'''''</code> (existing domain) you would use<br />
ln -s /srv/'''''example.com''''' /srv/'''''example.org'''''<br />
<br />
===Aliasing the Web Content Only===<br />
Slightly more complicated, but more flexible is to alias only the <code>public/</code> or <code>public/htdocs/</code> directory. This allows separate email, SSL certificates and individual, which don't reference the main domain. Some sites access content at the directory above <code>htdocs/</code>, in which case you should link at the <code>public/</code> point, otherwise <code>public/htdocs/</code> is usually preferable as it provides separate logging and allows individual FTP access.<br />
<br />
In the examples below, <code>example.com</code> is the site which already exists, and <code>example.org</code> is the new domain.<br />
<br />
====Aliasing public/htdocs/ Only====<br />
mkdir -p /srv/example.org/public<br />
ln -s /srv/example.com/public/htdocs /srv/example.org/public/htdocs<br />
touch /srv/example.org/config/disable-php-security<br />
<br />
====Aliassing public/ and Subdirectories====<br />
mkdir -p /srv/example.org<br />
ln -s /srv/example.com/public /srv/example.org/public<br />
touch /srv/example.org/config/disable-php-security<br />
<br />
====A Note on PHP Security====<br />
By default, PHP processes are restricted to the specific <code>public/</code> directory. This is fine in normal use, but as the links created above are resolved to their targets, they don't match the paths expected and will cause PHP errors. As a workaround, creating the <code>config/disable-php-security</code> file for the new alias disables this restriction, slightly reducing the security of the sites.<br />
<br />
==Serving Content on an Alternate IP Address==<br />
<blockquote>Note that the IP addresses must be valid IPs allocated and routed to your server for this to function.</blockquote>By default, Sympl uses the primary IP addresses (both IPv4 and IPv6) to serve content on. To override this and serve content via another IP address, add the IPs to <code>/srv/'''''example.com'''''/config/ip</code>, followed by <code>sudo sympl-configure-ips</code> to automatically add the IP addresses to the relevant interface, and <code>sudo sympl-configure-ips</code> to adjust the apache configuration to use the new IPs, at which point you should update the DNS for the domain.<br />
<br />
==Hidden Files and Directories==<br />
{{Template:Sympl 12 Only}}<br />
By default, Sympl blocks any hidden files or directories (those with filenames that start with a dot, '<code>.</code>') from being served via the web, such as <code>.user.ini</code>, <code>.htaccess</code>, files in <code>.git</code> and so on.<br />
<br />
If needed, this can be turned off by creating the file <code>config/allow-hidden</code>, but when doing so you should ensure access to any sensitive files are restricted by <code>.htaccess</code>.<br />
<br />
==Enforcing HTTPS==<br />
By default, Sympl will attempt to download a [[Let's Encrypt]] [[SSL Certificate|SSL certificate]] for each site automatically, and will then adjust the Apache configuration to enable it.<br />
<br />
In many cases you will likely want to enforce HTTPS usage on a domain to ensure end-to-end security, and this can be done easily by creating the file <code>/srv/'''''example.com'''''/config/ssl-only</code>.<br />
<br />
This change will take effect automatically within the next hour, but requires a working certificate.<br />
<br />
===HTTP Strict Transport Security (HSTS)===<br />
Once SSL has been enforced, you may also want to ensure users only ever access the site via HTTPS. This can be done by enabling [[HTTP Strict Transport Security|HSTS]], which instructs the users browser to only connect via HTTPS for the next six months.<br />
<br />
You should ensure the site is working properly via HTTPS before enabling this function, but once done, create the file <code>/srv/'''''example.com'''''/config/hsts</code> and the configuration will be updated within the next hour.<br />
<br />
==Redirecting to a Preferred Domain==<br />
In the event you want to force all traffic to the same domain name, this can be done with an [[Apache Rewrites|Apache rewrite]]. This this example, we want to ensure the domain being used is always <code>www.'''''example.com'''''</code>, preventing anyone from using <code>'''''example.com'''''</code> without the <code>www.</code>.<br />
<br />
To do this, you would create a file named <code>.htaccess</code> in the <code>htdocs/</code> directory with this content:<br />
RewriteEngine on<br />
RewriteCond %{HTTP_HOST} !^www.*$ [NC]<br />
RewriteRule ^(.*)$ <nowiki>http://www.%{HTTP_HOST}/$1</nowiki> [R=302,L]<br />
What this set of rules do is:<br />
<br />
#Enable the rewriting of content.<br />
#If the hostname being used does not start with 'www.' (case insensitive)<br />
#Temporarily redirect the request to the same hostname but with 'www.' added and don't process any rules.<br />
<br />
Once this is working as expected, you can change the <code>R=302</code> to <code>R=301</code> to swap the temporary redirect to a permanent one which will be cached by the browser.<blockquote>More information is available at ''[[Apache Rewrites]]''.</blockquote><br />
<br />
==Filesystem Permissions==<br />
By default, Sympl adjusts the permissions of files and directories in <code>/srv/'''''example.com'''''/public</code> to ensure web applications can update themselves correctly, and FTP users can make changes as desired.<br />
<br />
This defaults to changing the files and directories to be readable, writable, and owned by the <code>www-data</code> user and the <code>www-data</code> group (which the <code>sympl</code> user is a member of). These defaults can be changed by placing the name or ID of the desired user and group into <code>config/public-user</code> and <code>config/public-group</code>.<br />
<br />
This functionality can be coupled with individual PHP instances for each site (not yet implemented in Sympl) or can be disabled on each domain by creating the file <code>/srv/'''''example.com'''''/config/disable-filesystem-security</code>.<blockquote>See ''[[Filesystem Security]]'' for more information.</blockquote><br />
<br />
==Logging==<br />
By default, the Apache logs are written to <code>/srv/'''''example.com'''''/public/logs</code>, named as either <code>access.log</code> and <code>error.log</code> for HTTP requests, and <code>ssl_access.log</code> and <code>ssl_error.log</code> for HTTPS.<br />
<br />
These are automatically rotated daily, and compressed after two days.<br />
<br />
For any sites being served with [[Mass Hosting|mass hosting]], the logs can be found at <code>/var/log/apache2/zz-mass-hosting.access.log</code> and <code>/var/log/apache2/zz-mass-hosting.error.log</code> .<br />
<br />
Logging for any other traffic is written to <code>/var/log/apache2/other_vhosts_access.log</code>, with any errors for Apache itself at <code>/var/log/apache2/error.log</code>.<br />
<br />
==Web Statistics==<br />
Basic traffic statistics can be optionally generated for the domain from the web logs using [[AWFFull]] (or [[Webalizer]] on Sympl 10 and older), and are written to <code>/srv/'''''example.com'''''/public/htdocs/stats</code>, making them available at <code>https://'''''example.com'''''/stats</code>. <br />
<br />
To trigger the generation, create a file at <code>/srv/'''''example.com'''''/config/stats</code>, and they will be generated automatically overnight for the previous day(s).<br />
<br />
As they contain potentially sensitive information (i.e. client IPs), they are automatically protected by a username and password. To access them you must create a username and password in <code>config/stats-htaccess</code> using <code>htpasswd</code>:<blockquote>'''Note:''' If the file already exists, you should omit the -c parameter or a fresh configuration file will be created and overwrite anything there.</blockquote><br />
htpasswd -c /srv/'''''example.com'''''/config/stats-htaccess '''''username'''''<br />
You will be prompted for a password and confirmation, and you will then be able to log in.<br />
<br />
A template for Webalizer will automatically be written to <code>config/webalizer.conf</code> when the statistics are created, and this can be edited as desired.<br />
<br />
==CGI Scripts==<br />
CGI Scripts are executable code of some kind (binaries or scripts) which are run directly on the operating system, and return the content for a page. Due to them being executable they can be a security risk, so caution should be taken when using them. Usage of CGI Scripts has mostly been supplanted by [[PHP]], however some legacy code <br />
<br />
To use CGI Scripts on your domain, you should copy them to <code>/srv/'''''example.com'''''/public/cgi-bin/</code> and they will then be served at <code>http://'''''example.com'''''/cgi-bin/</code> as long as the files are set executable. Non-executable files will result in an error message rather than serving the content of the file.<br />
<br />
Any files in the <code>public/cgi-bin</code> will not have their permissions updated by <code>sympl-filesystem-security</code>, so it is up to the user to ensure they are set securely, and readable only by the relevant users. Typically they are not be expected to be writable.<br />
<br />
==Custom Additions to the Apache Configuration==<br />
For sites with individual configuration files, custom additions can be made to the Apache configuration by adding files with the <code>.conf</code> extension to <code>/srv/'''''example.com'''''/conf/apache.d/</code>. These will be read when Apache is reloaded or started, and can be used to make changes to the configuration without using <code>.htaccess</code> files.<br />
<br />
The configuration can be tested with <code>sudo apachectl -t</code> and Apache reloaded with <code>sudo service apache2 reload</code>.<br />
<br />
Extreme care should be taken when using this feature, as an invalid configuration will prevent Apache from starting, as as such is considered a feature for advanced users only.<br />
<br />
==Further Modifying the Apache Configuration==<br />
The majority of typical changes to the Apache configuration can be made via relevant <code>.htaccess</code> files, with most of others available via <code>conf/apache.d/</code>.<br />
<br />
In the event you need to make custom changes to the Apache configuration for an individual site, configuration files can be found in <code>/etc/apache/sites-enabled</code>. Note that if you do make any changes, the configuration will no longer be managed by Sympl and it won't make any changes if the templates are updated. If you want to revert to a Sympl generated configuration for a specific domain, you can do this with <code>sudo sympl-web-configure --verbose '''''example.com'''''</code><br />
<br />
If you want to update the configuration of all sites, then you can edit the templates used to generate the Apache configurations, but you should take care when making any changes to ensure the result is valid. These can be found in <code>/etc/sympl/apache.d</code>, and the existing templated configurations can be regenerated with <code>sudo sympl-web-configure --verbose</code>. Note that any changes to the template files will prevent the templates from being automatically updated, pause updates to the <code>sympl-web</code> package until <br />
<br />
Finally, if you want to create your own Apache configurations not managed by Sympl you can do, as it will not make any changes to them.<br />
<br />
==Configuration Reference==<br />
<section begin="config" /><br />
{| class="wikitable sortable"<br />
|+<br />
!File or Directory<br />
!Used For<br />
!<br />
|-<br />
|<code>.../config/ip</code><br />
|Contains a list of IP addresses which a website will be bound to. Defaults to the primary IPs (IPv4 and IPv6) of your server.<br />
|[[Website Configuration Reference#Serving Content on an Alternate IP Address.|<small>More...</small>]]<br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/ssl-only</code><br />
|Redirects all non-HTTPS traffic for the site to HTTPS.<br />
|[[Website Configuration Reference#Enforcing HTTPS|<small>More...</small>]]<br />
|-<br />
|<code>.../config/hsts</code><br />
|Enables HSTS for HTTPS sites.<br />
|<small>[[Website Configuration Reference#HTTP Strict Transport Security (HSTS)|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/php</code><br />
|Selects the PHP version the site should be run under. Remove the file to default to the bundled version for your distribution.<br />
|<small>[[Website Configuration Reference#Selecting a PHP Version|More...]]</small><br />
|-<br />
|<code>.../config/php-modules</code><br />
|A list of PHP modules/extension package names for the site which will be installed automatically.<br />
|<small>[[Website Configuration Reference#Selecting a PHP Version|More...]]</small><br />
|-<br />
|<code>.../config/php-pool<br />
|Defines the alphanumeric name of the PHP pool for the site.<br />
|<small>[[Website Configuration Reference#Selecting a PHP Version|More...]]</small><br />
|-<br />
|<code>.../config/php-user</code><br />
|The local system user to run the PHP process as.<br />
|<small>[[Website Configuration Reference#Extended Configuration|More...]]</small><br />
|-<br />
|<code>.../config/php-group</code><br />
|The local group to run the PHP process as.<br />
|<small>[[Website Configuration Reference#Extended Configuration|More...]]</small><br />
|-<br />
|<code>.../config/disable-php-security</code><br />
|Existence of this file will disable some of the PHP security functions in the automatically generated [[Apache]] configurations.<br />
|<small>[[Website Configuration Reference#PHP Security|More...]]</small><br />
|-<br />
|<code>/etc/sympl/php/<version>/includes.d/<pool_name>.conf</code><br />
|Configuration changes for a specific PHP pool should be placed here.<br />
|<small>[[Website Configuration Reference#Extended Configuration|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/allow-hidden</code><br />
|Existence of this file will allow the website to serve files which are usually hidden.<br />
|<small>[[Website Configuration Reference#Hidden Files and Directories|More...]]</small><br />
|-<br />
|<code>.../config/disable-filesystem-security</code><br />
|Existence of this file will disable the automatic filesystem security tasks on this domain.<br />
|<small>[[Website Configuration Reference#Filesystem Permissions|More...]]</small><br />
|-<br />
|<code>.../config/public-user</code><br />
|UID or user name of the user to change ownership of the <code>public/</code> directory to. Defaults to www-data.<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
|<code>.../config/public-group</code><br />
|GID or group name of the user to change ownership of the <code>public/</code> directory to. Defaults to www-data.<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/stats</code><br />
|This file enables automatic generation of [[Web Statistics|web stats]] with [[Awffull]]/[[Webalizer]]<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
|<code>.../config/stats-htaccess</code><br />
|A '[[htpasswd]]' format file used to access the [[Web Statistics|web stats]].<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
|<code>.../config/apache.d/'''''example'''''.conf</code><br />
|Apache config files to be included in the site configuration.<br />
|<small>[[Website Configuration Reference#Custom Additions to the Apache Configuration|More...]]</small><br />
|}<section end="config" /><br />
<br />
<blockquote>See also [[Configuration Reference|''Configuration Reference'']] for other configuration files.</blockquote><br />
[[Category:Web]]<br />
[[Category:Reference]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Website_Configuration_Reference&diff=5019Website Configuration Reference2023-06-12T18:25:18Z<p>Kelduum: /* Redirecting to a Preferred Domain */</p>
<hr />
<div>This page is a detailed breakdown of all the configuration options and files available when configuring website hosting on Sympl.<br />
<br />
As with all the other documentation here, the site <code>'''''example.com'''''</code> will used, and you should substitute this for your domain.<br />
<br />
All configuration for this domain will be in the /srv/example.com/ directory.<br />
<br />
Sympl uses the [[Apache]] web server, along with the relevant version of [[PHP]] for your version of [[Debian]], along with the typical PHP extensions. See [[Supported PHP Versions]].<br />
<br />
==Getting Started==<br />
The files for example.com are in the <code>/srv/'''''example.com'''''/public/htdocs</code> directory which is the site root.<br />
<br />
*If this directory doesn't exist, is empty, or has no <code>index.php</code> or <code>index.html</code>, the default page will be served, mentioning there is no content on the site.<br />
*The content in the directory will be served for both www.example.com and example.com, so theres no need to prefix the domain with www.<br />
*If you want to serve different content for www.example.com and example.com, you can create /srv/www.example.com as a separate directory.<br />
*Within an hour of the directory creation, a new configuration will [[Sympl-web-configure|automatically be created]] for Apache.<br />
<br />
More detailed information about how Sympl serves content can be found at ''[[How Web Hosting Works on Sympl]]''.<br />
<br />
==Testing Your Sites==<br />
New sites can be tested before they are made live using the 'testing' domains. If your hosting provider provides a wildcard DNS entry on your server pointing to its hostname (and the [[Default Site|default site]] is set to match), then sites can be accessed via this method.<br />
<br />
You can confirm if this is the case using <code>dig</code> or a similar tool - if your server is named <code>'''''server.example.host'''''</code>, if you run <code>dig +short randomname.'''''server.example.host'''''</code> and get a response with the server's IP address, then this is the case.<br />
<br />
If so, you can access any of the sites via this method in the format <domain_directory>.testing.<server_hostname>, for example <code>'''''example.com'''''.testing.'''''server.example.host'''''</code>. Note that the <code>www.</code> should not be included in this case.<br />
<br />
Note that this only applies to websites (not email, FTP and similar), and will not work fully in all instances, as some sites will redirect to their expected hostname or similar. If this is the case, you can test by [[Editing Your Hosts File|editing your hosts file]] on your local computer.<br />
<br />
== PHP Configuration ==<br />
<br />
PHP is the scripting language which the popular Content Management Systems and most websites is written in. It's very popular due to it's flexibility and ease of use, which means that the development of PHP moves quickly, with new versions released every year or so.<br />
<br />
With PHP development moving quickly, the Debian release cycle being every two years, and the common need to run sites on older versions, it's not uncommon to see an instance where you need a different version of PHP than the one bundled with the operating system.<br />
<br />
=== Selecting a PHP Version ===<br />
This isn't currently possible to do automatically on Sympl 11 and earlier, there are community-supported work-arounds. Sympl 12 adds support for selectable PHP versions, and this functionality is being back-ported to earlier versions.<br />
<br />
{{Template:Sympl 12 Only}}<br />
To select a PHP version for a specific site, place the PHP major and minor versions (such as '5.6', '7.3' or '8.1') in the file <code>config/php</code> and run <code>sudo sympl-php-configure</code>.<br />
<br />
This will then install the relevant PHP version from [https://deb.sury.org https://deb.sury.org] if required, along with the typical PHP packages, and configure the site to use that PHP version. Note there is a small extra disk space requirement for each extra version of PHP installed.<br />
<br />
If other PHP modules/extensions are required for the site, their package names can be placed in <code>config/php-modules</code>, and they will be installed automatically the next time <code>sudo sympl-php-configure</code> is run. Package names are the name of the Debian packaged modules without the PHP version, so the <code>php8.1-tidy</code> package would be listed in the file as <code>tidy</code>. PHP extensions can also be installed manually using apt.<br />
<br />
All sites default to a pool named 'default' unless specified otherwise in <code>config/php-pool</code>. If you require any configuration changes, or wish to adjust resources for a site, you should configure it with it's own pool. Note that each pool has its own memory requirements and PHP instances standing by, so running a large number of pools will consume more RAM on your server.<br />
<br />
=== .htaccess vs .user.ini ===<br />
{{Template:Sympl 12 Only}}<br />
When using the default PHP version (ie: not specifying one) the site will run under the default PHP version for the distribution (ie: PHP 8.2 for Debian Bookworm) using 'mod_apache'. This will parse PHP variables and overrides via the <code>.htaccess</code> file in the web content directory, allowing you to make changes on a per-directory basis.<br />
<br />
Running a site under 'FPM' as the configured sites do means they are only passed the relevant file, so require the same configuration entries in a slightly different format in the file <code>.user.ini</code> file, in the same location as <code>.htaccess</code>.<br />
<br />
If you don't already have a <code>.user.ini</code> file in place, Sympl will automatically create and manage one for you each time <code>sudo sympl-php-configure</code> is run. <br />
<br />
=== PHP Command Line ===<br />
{{Template:Sympl 12 Only}}<br />
In some instances, you may need to run the PHP from the command line but need a version other than the default. To do so, rather than using the plain <code>php example.php</code> command, simply append the version, for example <code>php8.1 example.php</code>.<br />
<br />
=== Extended Configuration ===<br />
{{Template:Sympl 12 Only}}<br />
Sympl supports a number of other extended configuration options, including selectable user and group that the PHP pool should be executed as, with <code>config/php-user</code> and <code>config/php-group</code> respectively. These default to www-data, but if must exist if they are changed, and cannot be system users (ie: with an ID below 1000). Note that these settings also inherit the values of <code>public-user</code> and <code>public-group</code> if set.<br />
<br />
As the PHP pool files are managed automatically by Sympl to ensure that PHP continues running, manual changes to the pool configurations will be overwritten on each run. If a change to a pool configuration is required, extra configuration lines can be added to <code>/etc/sympl/php/<version>/includes.d/<pool_name>.conf</code>. The pool name is defined as <code><pool_name>[_<username>[_<groupname>]]</code> with the username and group being optional if not left on the default.<br />
<br />
===PHP Security===<br />
By default, a number of rules are included in the Apache configuration which limit the access of sites running PHP, preventing a compromised site from accessing content outside the <code>/srv/example.com/public/</code> directory, and setting both a domain-specific temp directory and session directory as <code>/srv/example.com/php_tmp/</code> and <code>/srv/example.com/php_sessions/</code> respectively.<br />
<br />
A default configuration is also in place for the ever-popular [[WordPress]], which prevents PHP files from being accessed or executed from within the upload folder, which tend to be the source of most site compromises.<br />
<br />
These restrictions can be disabled by creating the file <code>/srv/example.com/config/disable-php-security</code>, and running <code>sudo sympl-web-configure</code>.<br />
<br />
====PHP Lockdown====<br />
Also available but not enabled by default is a '[[PHP Lockdown|lockdown]]' configuration, which limits a number of potentially dangerous functions in PHP for ''all sites'' where a PHP version is not selected.<br />
<br />
This can be enabled with the command line...<br />
<br />
'''For Sympl 10.x'''<br />
sudo ln -s /etc/php/7.0/mods-available/sympl-web-lockdown.ini /etc/php/7.0/apache2/conf.d/01-sympl-web-lockdown.ini<br />
sudo service apache2 reload<br />
'''For Sympl 11.x'''<br />
sudo ln -s /etc/php/7.3/mods-available/sympl-web-lockdown.ini /etc/php/7.3/apache2/conf.d/01-sympl-web-lockdown.ini<br />
sudo service apache2 reload<br />
'''For Sympl 12.x'''<br />
sudo ln -s /etc/php/8.2/mods-available/sympl-web-lockdown.ini /etc/php/8.2/apache2/conf.d/01-sympl-web-lockdown.ini<br />
sudo service apache2 reload<br />
<br />
Note that this will significantly restrict PHP access, and will affect all sites on the same server, so you should confirm that all sites work as expected once this has been run.<br />
<br />
==Serving the Same Content on Multiple Domains.==<br />
In some cases you may want to accept traffic for and serve the same content for multiple domains, such as [[WordPress Multi-site|WordPress multi-site]] configurations.<br />
<br />
Both of these assume you have the main site already configured and working.<br />
<br />
===Aliasing the Whole Domain===<br />
The most simple option is to alias the whole domain. This will result in the whole configuration including other services such as email, SSL certificates, and FTP sites all sharing the same domain.<br />
<br />
To do this, you only need to create a [[Symbolic Link|symbolic link]] to the directory of the site you want to alias. Aliasing <code>'''''example.org'''''</code> (new domain) to <code>'''''example.com'''''</code> (existing domain) you would use<br />
ln -s /srv/'''''example.com''''' /srv/'''''example.org'''''<br />
<br />
===Aliasing the Web Content Only===<br />
Slightly more complicated, but more flexible is to alias only the <code>public/</code> or <code>public/htdocs/</code> directory. This allows separate email, SSL certificates and individual, which don't reference the main domain. Some sites access content at the directory above <code>htdocs/</code>, in which case you should link at the <code>public/</code> point, otherwise <code>public/htdocs/</code> is usually preferable as it provides separate logging and allows individual FTP access.<br />
<br />
In the examples below, <code>example.com</code> is the site which already exists, and <code>example.org</code> is the new domain.<br />
<br />
====Aliasing public/htdocs/ Only====<br />
mkdir -p /srv/example.org/public<br />
ln -s /srv/example.com/public/htdocs /srv/example.org/public/htdocs<br />
touch /srv/example.org/config/disable-php-security<br />
<br />
====Aliassing public/ and Subdirectories====<br />
mkdir -p /srv/example.org<br />
ln -s /srv/example.com/public /srv/example.org/public<br />
touch /srv/example.org/config/disable-php-security<br />
<br />
====A Note on PHP Security====<br />
By default, PHP processes are restricted to the specific <code>public/</code> directory. This is fine in normal use, but as the links created above are resolved to their targets, they don't match the paths expected and will cause PHP errors. As a workaround, creating the <code>config/disable-php-security</code> file for the new alias disables this restriction, slightly reducing the security of the sites.<br />
<br />
==Serving Content on an Alternate IP Address==<br />
<blockquote>Note that the IP addresses must be valid IPs allocated and routed to your server for this to function.</blockquote>By default, Sympl uses the primary IP addresses (both IPv4 and IPv6) to serve content on. To override this and serve content via another IP address, add the IPs to <code>/srv/'''''example.com'''''/config/ip</code>, followed by <code>sudo sympl-configure-ips</code> to automatically add the IP addresses to the relevant interface, and <code>sudo sympl-configure-ips</code> to adjust the apache configuration to use the new IPs, at which point you should update the DNS for the domain.<br />
<br />
==Hidden Files==<br />
{{Template:Sympl 12 Only}}<br />
By default, Sympl blocks any hidden files or directories (those with filenames that start with a dot, '<code>.</code>') from being served via the web, such as <code>.user.ini</code>, <code>.htaccess</code>, files in <code>.git</code> and so on.<br />
<br />
If needed, this can be turned off by creating the file <code>config/allow-hidden</code>, but when doing so you should ensure access to any sensitive files are restricted by <code>.htaccess</code>.<br />
<br />
==Enforcing HTTPS==<br />
By default, Sympl will attempt to download a [[Let's Encrypt]] [[SSL Certificate|SSL certificate]] for each site automatically, and will then adjust the Apache configuration to enable it.<br />
<br />
In many cases you will likely want to enforce HTTPS usage on a domain to ensure end-to-end security, and this can be done easily by creating the file <code>/srv/'''''example.com'''''/config/ssl-only</code>.<br />
<br />
This change will take effect automatically within the next hour, but requires a working certificate.<br />
<br />
===HTTP Strict Transport Security (HSTS)===<br />
Once SSL has been enforced, you may also want to ensure users only ever access the site via HTTPS. This can be done by enabling [[HTTP Strict Transport Security|HSTS]], which instructs the users browser to only connect via HTTPS for the next six months.<br />
<br />
You should ensure the site is working properly via HTTPS before enabling this function, but once done, create the file <code>/srv/'''''example.com'''''/config/hsts</code> and the configuration will be updated within the next hour.<br />
<br />
==Redirecting to a Preferred Domain==<br />
In the event you want to force all traffic to the same domain name, this can be done with an [[Apache Rewrites|Apache rewrite]]. This this example, we want to ensure the domain being used is always <code>www.'''''example.com'''''</code>, preventing anyone from using <code>'''''example.com'''''</code> without the <code>www.</code>.<br />
<br />
To do this, you would create a file named <code>.htaccess</code> in the <code>htdocs/</code> directory with this content:<br />
RewriteEngine on<br />
RewriteCond %{HTTP_HOST} !^www.*$ [NC]<br />
RewriteRule ^(.*)$ <nowiki>http://www.%{HTTP_HOST}/$1</nowiki> [R=302,L]<br />
What this set of rules do is:<br />
<br />
#Enable the rewriting of content.<br />
#If the hostname being used does not start with 'www.' (case insensitive)<br />
#Temporarily redirect the request to the same hostname but with 'www.' added and don't process any rules.<br />
<br />
Once this is working as expected, you can change the <code>R=302</code> to <code>R=301</code> to swap the temporary redirect to a permanent one which will be cached by the browser.<blockquote>More information is available at ''[[Apache Rewrites]]''.</blockquote><br />
<br />
==Filesystem Permissions==<br />
By default, Sympl adjusts the permissions of files and directories in <code>/srv/'''''example.com'''''/public</code> to ensure web applications can update themselves correctly, and FTP users can make changes as desired.<br />
<br />
This defaults to changing the files and directories to be readable, writable, and owned by the <code>www-data</code> user and the <code>www-data</code> group (which the <code>sympl</code> user is a member of). These defaults can be changed by placing the name or ID of the desired user and group into <code>config/public-user</code> and <code>config/public-group</code>.<br />
<br />
This functionality can be coupled with individual PHP instances for each site (not yet implemented in Sympl) or can be disabled on each domain by creating the file <code>/srv/'''''example.com'''''/config/disable-filesystem-security</code>.<blockquote>See ''[[Filesystem Security]]'' for more information.</blockquote><br />
<br />
==Logging==<br />
By default, the Apache logs are written to <code>/srv/'''''example.com'''''/public/logs</code>, named as either <code>access.log</code> and <code>error.log</code> for HTTP requests, and <code>ssl_access.log</code> and <code>ssl_error.log</code> for HTTPS.<br />
<br />
These are automatically rotated daily, and compressed after two days.<br />
<br />
For any sites being served with [[Mass Hosting|mass hosting]], the logs can be found at <code>/var/log/apache2/zz-mass-hosting.access.log</code> and <code>/var/log/apache2/zz-mass-hosting.error.log</code> .<br />
<br />
Logging for any other traffic is written to <code>/var/log/apache2/other_vhosts_access.log</code>, with any errors for Apache itself at <code>/var/log/apache2/error.log</code>.<br />
<br />
==Web Statistics==<br />
Basic traffic statistics can be optionally generated for the domain from the web logs using [[AWFFull]] (or [[Webalizer]] on Sympl 10 and older), and are written to <code>/srv/'''''example.com'''''/public/htdocs/stats</code>, making them available at <code>https://'''''example.com'''''/stats</code>. <br />
<br />
To trigger the generation, create a file at <code>/srv/'''''example.com'''''/config/stats</code>, and they will be generated automatically overnight for the previous day(s).<br />
<br />
As they contain potentially sensitive information (i.e. client IPs), they are automatically protected by a username and password. To access them you must create a username and password in <code>config/stats-htaccess</code> using <code>htpasswd</code>:<blockquote>'''Note:''' If the file already exists, you should omit the -c parameter or a fresh configuration file will be created and overwrite anything there.</blockquote><br />
htpasswd -c /srv/'''''example.com'''''/config/stats-htaccess '''''username'''''<br />
You will be prompted for a password and confirmation, and you will then be able to log in.<br />
<br />
A template for Webalizer will automatically be written to <code>config/webalizer.conf</code> when the statistics are created, and this can be edited as desired.<br />
<br />
==CGI Scripts==<br />
CGI Scripts are executable code of some kind (binaries or scripts) which are run directly on the operating system, and return the content for a page. Due to them being executable they can be a security risk, so caution should be taken when using them. Usage of CGI Scripts has mostly been supplanted by [[PHP]], however some legacy code <br />
<br />
To use CGI Scripts on your domain, you should copy them to <code>/srv/'''''example.com'''''/public/cgi-bin/</code> and they will then be served at <code>http://'''''example.com'''''/cgi-bin/</code> as long as the files are set executable. Non-executable files will result in an error message rather than serving the content of the file.<br />
<br />
Any files in the <code>public/cgi-bin</code> will not have their permissions updated by <code>sympl-filesystem-security</code>, so it is up to the user to ensure they are set securely, and readable only by the relevant users. Typically they are not be expected to be writable.<br />
<br />
==Custom Additions to the Apache Configuration==<br />
For sites with individual configuration files, custom additions can be made to the Apache configuration by adding files with the <code>.conf</code> extension to <code>/srv/'''''example.com'''''/conf/apache.d/</code>. These will be read when Apache is reloaded or started, and can be used to make changes to the configuration without using <code>.htaccess</code> files.<br />
<br />
The configuration can be tested with <code>sudo apachectl -t</code> and Apache reloaded with <code>sudo service apache2 reload</code>.<br />
<br />
Extreme care should be taken when using this feature, as an invalid configuration will prevent Apache from starting, as as such is considered a feature for advanced users only.<br />
<br />
==Further Modifying the Apache Configuration==<br />
The majority of typical changes to the Apache configuration can be made via relevant <code>.htaccess</code> files, with most of others available via <code>conf/apache.d/</code>.<br />
<br />
In the event you need to make custom changes to the Apache configuration for an individual site, configuration files can be found in <code>/etc/apache/sites-enabled</code>. Note that if you do make any changes, the configuration will no longer be managed by Sympl and it won't make any changes if the templates are updated. If you want to revert to a Sympl generated configuration for a specific domain, you can do this with <code>sudo sympl-web-configure --verbose '''''example.com'''''</code><br />
<br />
If you want to update the configuration of all sites, then you can edit the templates used to generate the Apache configurations, but you should take care when making any changes to ensure the result is valid. These can be found in <code>/etc/sympl/apache.d</code>, and the existing templated configurations can be regenerated with <code>sudo sympl-web-configure --verbose</code>. Note that any changes to the template files will prevent the templates from being automatically updated, pause updates to the <code>sympl-web</code> package until <br />
<br />
Finally, if you want to create your own Apache configurations not managed by Sympl you can do, as it will not make any changes to them.<br />
<br />
==Configuration Reference==<br />
<section begin="config" /><br />
{| class="wikitable sortable"<br />
|+<br />
!File or Directory<br />
!Used For<br />
!<br />
|-<br />
|<code>.../config/ip</code><br />
|Contains a list of IP addresses which a website will be bound to. Defaults to the primary IPs (IPv4 and IPv6) of your server.<br />
|[[Website Configuration Reference#Serving Content on an Alternate IP Address.|<small>More...</small>]]<br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/ssl-only</code><br />
|Redirects all non-HTTPS traffic for the site to HTTPS.<br />
|[[Website Configuration Reference#Enforcing HTTPS|<small>More...</small>]]<br />
|-<br />
|<code>.../config/hsts</code><br />
|Enables HSTS for HTTPS sites.<br />
|<small>[[Website Configuration Reference#HTTP Strict Transport Security (HSTS)|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/php</code><br />
|Selects the PHP version the site should be run under. Remove the file to default to the bundled version for your distribution.<br />
|<small>[[Website Configuration Reference#Selecting a PHP Version|More...]]</small><br />
|-<br />
|<code>.../config/php-modules</code><br />
|A list of PHP modules/extension package names for the site which will be installed automatically.<br />
|<small>[[Website Configuration Reference#Selecting a PHP Version|More...]]</small><br />
|-<br />
|<code>.../config/php-pool<br />
|Defines the alphanumeric name of the PHP pool for the site.<br />
|<small>[[Website Configuration Reference#Selecting a PHP Version|More...]]</small><br />
|-<br />
|<code>.../config/php-user</code><br />
|The local system user to run the PHP process as.<br />
|<small>[[Website Configuration Reference#Extended Configuration|More...]]</small><br />
|-<br />
|<code>.../config/php-group</code><br />
|The local group to run the PHP process as.<br />
|<small>[[Website Configuration Reference#Extended Configuration|More...]]</small><br />
|-<br />
|<code>.../config/disable-php-security</code><br />
|Existence of this file will disable some of the PHP security functions in the automatically generated [[Apache]] configurations.<br />
|<small>[[Website Configuration Reference#PHP Security|More...]]</small><br />
|-<br />
|<code>/etc/sympl/php/<version>/includes.d/<pool_name>.conf</code><br />
|Configuration changes for a specific PHP pool should be placed here.<br />
|<small>[[Website Configuration Reference#Extended Configuration|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/allow-hidden</code><br />
|Existence of this file will allow the website to serve files which are usually hidden.<br />
|<small>[[Website Configuration Reference#Hidden Files and Directories|More...]]</small><br />
|-<br />
|<code>.../config/disable-filesystem-security</code><br />
|Existence of this file will disable the automatic filesystem security tasks on this domain.<br />
|<small>[[Website Configuration Reference#Filesystem Permissions|More...]]</small><br />
|-<br />
|<code>.../config/public-user</code><br />
|UID or user name of the user to change ownership of the <code>public/</code> directory to. Defaults to www-data.<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
|<code>.../config/public-group</code><br />
|GID or group name of the user to change ownership of the <code>public/</code> directory to. Defaults to www-data.<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/stats</code><br />
|This file enables automatic generation of [[Web Statistics|web stats]] with [[Awffull]]/[[Webalizer]]<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
|<code>.../config/stats-htaccess</code><br />
|A '[[htpasswd]]' format file used to access the [[Web Statistics|web stats]].<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
|<code>.../config/apache.d/'''''example'''''.conf</code><br />
|Apache config files to be included in the site configuration.<br />
|<small>[[Website Configuration Reference#Custom Additions to the Apache Configuration|More...]]</small><br />
|}<section end="config" /><br />
<br />
<blockquote>See also [[Configuration Reference|''Configuration Reference'']] for other configuration files.</blockquote><br />
[[Category:Web]]<br />
[[Category:Reference]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Website_Configuration_Reference&diff=5018Website Configuration Reference2023-06-12T18:24:57Z<p>Kelduum: /* Configuration Reference */</p>
<hr />
<div>This page is a detailed breakdown of all the configuration options and files available when configuring website hosting on Sympl.<br />
<br />
As with all the other documentation here, the site <code>'''''example.com'''''</code> will used, and you should substitute this for your domain.<br />
<br />
All configuration for this domain will be in the /srv/example.com/ directory.<br />
<br />
Sympl uses the [[Apache]] web server, along with the relevant version of [[PHP]] for your version of [[Debian]], along with the typical PHP extensions. See [[Supported PHP Versions]].<br />
<br />
==Getting Started==<br />
The files for example.com are in the <code>/srv/'''''example.com'''''/public/htdocs</code> directory which is the site root.<br />
<br />
*If this directory doesn't exist, is empty, or has no <code>index.php</code> or <code>index.html</code>, the default page will be served, mentioning there is no content on the site.<br />
*The content in the directory will be served for both www.example.com and example.com, so theres no need to prefix the domain with www.<br />
*If you want to serve different content for www.example.com and example.com, you can create /srv/www.example.com as a separate directory.<br />
*Within an hour of the directory creation, a new configuration will [[Sympl-web-configure|automatically be created]] for Apache.<br />
<br />
More detailed information about how Sympl serves content can be found at ''[[How Web Hosting Works on Sympl]]''.<br />
<br />
==Testing Your Sites==<br />
New sites can be tested before they are made live using the 'testing' domains. If your hosting provider provides a wildcard DNS entry on your server pointing to its hostname (and the [[Default Site|default site]] is set to match), then sites can be accessed via this method.<br />
<br />
You can confirm if this is the case using <code>dig</code> or a similar tool - if your server is named <code>'''''server.example.host'''''</code>, if you run <code>dig +short randomname.'''''server.example.host'''''</code> and get a response with the server's IP address, then this is the case.<br />
<br />
If so, you can access any of the sites via this method in the format <domain_directory>.testing.<server_hostname>, for example <code>'''''example.com'''''.testing.'''''server.example.host'''''</code>. Note that the <code>www.</code> should not be included in this case.<br />
<br />
Note that this only applies to websites (not email, FTP and similar), and will not work fully in all instances, as some sites will redirect to their expected hostname or similar. If this is the case, you can test by [[Editing Your Hosts File|editing your hosts file]] on your local computer.<br />
<br />
== PHP Configuration ==<br />
<br />
PHP is the scripting language which the popular Content Management Systems and most websites is written in. It's very popular due to it's flexibility and ease of use, which means that the development of PHP moves quickly, with new versions released every year or so.<br />
<br />
With PHP development moving quickly, the Debian release cycle being every two years, and the common need to run sites on older versions, it's not uncommon to see an instance where you need a different version of PHP than the one bundled with the operating system.<br />
<br />
=== Selecting a PHP Version ===<br />
This isn't currently possible to do automatically on Sympl 11 and earlier, there are community-supported work-arounds. Sympl 12 adds support for selectable PHP versions, and this functionality is being back-ported to earlier versions.<br />
<br />
{{Template:Sympl 12 Only}}<br />
To select a PHP version for a specific site, place the PHP major and minor versions (such as '5.6', '7.3' or '8.1') in the file <code>config/php</code> and run <code>sudo sympl-php-configure</code>.<br />
<br />
This will then install the relevant PHP version from [https://deb.sury.org https://deb.sury.org] if required, along with the typical PHP packages, and configure the site to use that PHP version. Note there is a small extra disk space requirement for each extra version of PHP installed.<br />
<br />
If other PHP modules/extensions are required for the site, their package names can be placed in <code>config/php-modules</code>, and they will be installed automatically the next time <code>sudo sympl-php-configure</code> is run. Package names are the name of the Debian packaged modules without the PHP version, so the <code>php8.1-tidy</code> package would be listed in the file as <code>tidy</code>. PHP extensions can also be installed manually using apt.<br />
<br />
All sites default to a pool named 'default' unless specified otherwise in <code>config/php-pool</code>. If you require any configuration changes, or wish to adjust resources for a site, you should configure it with it's own pool. Note that each pool has its own memory requirements and PHP instances standing by, so running a large number of pools will consume more RAM on your server.<br />
<br />
=== .htaccess vs .user.ini ===<br />
{{Template:Sympl 12 Only}}<br />
When using the default PHP version (ie: not specifying one) the site will run under the default PHP version for the distribution (ie: PHP 8.2 for Debian Bookworm) using 'mod_apache'. This will parse PHP variables and overrides via the <code>.htaccess</code> file in the web content directory, allowing you to make changes on a per-directory basis.<br />
<br />
Running a site under 'FPM' as the configured sites do means they are only passed the relevant file, so require the same configuration entries in a slightly different format in the file <code>.user.ini</code> file, in the same location as <code>.htaccess</code>.<br />
<br />
If you don't already have a <code>.user.ini</code> file in place, Sympl will automatically create and manage one for you each time <code>sudo sympl-php-configure</code> is run. <br />
<br />
=== PHP Command Line ===<br />
{{Template:Sympl 12 Only}}<br />
In some instances, you may need to run the PHP from the command line but need a version other than the default. To do so, rather than using the plain <code>php example.php</code> command, simply append the version, for example <code>php8.1 example.php</code>.<br />
<br />
=== Extended Configuration ===<br />
{{Template:Sympl 12 Only}}<br />
Sympl supports a number of other extended configuration options, including selectable user and group that the PHP pool should be executed as, with <code>config/php-user</code> and <code>config/php-group</code> respectively. These default to www-data, but if must exist if they are changed, and cannot be system users (ie: with an ID below 1000). Note that these settings also inherit the values of <code>public-user</code> and <code>public-group</code> if set.<br />
<br />
As the PHP pool files are managed automatically by Sympl to ensure that PHP continues running, manual changes to the pool configurations will be overwritten on each run. If a change to a pool configuration is required, extra configuration lines can be added to <code>/etc/sympl/php/<version>/includes.d/<pool_name>.conf</code>. The pool name is defined as <code><pool_name>[_<username>[_<groupname>]]</code> with the username and group being optional if not left on the default.<br />
<br />
===PHP Security===<br />
By default, a number of rules are included in the Apache configuration which limit the access of sites running PHP, preventing a compromised site from accessing content outside the <code>/srv/example.com/public/</code> directory, and setting both a domain-specific temp directory and session directory as <code>/srv/example.com/php_tmp/</code> and <code>/srv/example.com/php_sessions/</code> respectively.<br />
<br />
A default configuration is also in place for the ever-popular [[WordPress]], which prevents PHP files from being accessed or executed from within the upload folder, which tend to be the source of most site compromises.<br />
<br />
These restrictions can be disabled by creating the file <code>/srv/example.com/config/disable-php-security</code>, and running <code>sudo sympl-web-configure</code>.<br />
<br />
====PHP Lockdown====<br />
Also available but not enabled by default is a '[[PHP Lockdown|lockdown]]' configuration, which limits a number of potentially dangerous functions in PHP for ''all sites'' where a PHP version is not selected.<br />
<br />
This can be enabled with the command line...<br />
<br />
'''For Sympl 10.x'''<br />
sudo ln -s /etc/php/7.0/mods-available/sympl-web-lockdown.ini /etc/php/7.0/apache2/conf.d/01-sympl-web-lockdown.ini<br />
sudo service apache2 reload<br />
'''For Sympl 11.x'''<br />
sudo ln -s /etc/php/7.3/mods-available/sympl-web-lockdown.ini /etc/php/7.3/apache2/conf.d/01-sympl-web-lockdown.ini<br />
sudo service apache2 reload<br />
'''For Sympl 12.x'''<br />
sudo ln -s /etc/php/8.2/mods-available/sympl-web-lockdown.ini /etc/php/8.2/apache2/conf.d/01-sympl-web-lockdown.ini<br />
sudo service apache2 reload<br />
<br />
Note that this will significantly restrict PHP access, and will affect all sites on the same server, so you should confirm that all sites work as expected once this has been run.<br />
<br />
==Serving the Same Content on Multiple Domains.==<br />
In some cases you may want to accept traffic for and serve the same content for multiple domains, such as [[WordPress Multi-site|WordPress multi-site]] configurations.<br />
<br />
Both of these assume you have the main site already configured and working.<br />
<br />
===Aliasing the Whole Domain===<br />
The most simple option is to alias the whole domain. This will result in the whole configuration including other services such as email, SSL certificates, and FTP sites all sharing the same domain.<br />
<br />
To do this, you only need to create a [[Symbolic Link|symbolic link]] to the directory of the site you want to alias. Aliasing <code>'''''example.org'''''</code> (new domain) to <code>'''''example.com'''''</code> (existing domain) you would use<br />
ln -s /srv/'''''example.com''''' /srv/'''''example.org'''''<br />
<br />
===Aliasing the Web Content Only===<br />
Slightly more complicated, but more flexible is to alias only the <code>public/</code> or <code>public/htdocs/</code> directory. This allows separate email, SSL certificates and individual, which don't reference the main domain. Some sites access content at the directory above <code>htdocs/</code>, in which case you should link at the <code>public/</code> point, otherwise <code>public/htdocs/</code> is usually preferable as it provides separate logging and allows individual FTP access.<br />
<br />
In the examples below, <code>example.com</code> is the site which already exists, and <code>example.org</code> is the new domain.<br />
<br />
====Aliasing public/htdocs/ Only====<br />
mkdir -p /srv/example.org/public<br />
ln -s /srv/example.com/public/htdocs /srv/example.org/public/htdocs<br />
touch /srv/example.org/config/disable-php-security<br />
<br />
====Aliassing public/ and Subdirectories====<br />
mkdir -p /srv/example.org<br />
ln -s /srv/example.com/public /srv/example.org/public<br />
touch /srv/example.org/config/disable-php-security<br />
<br />
====A Note on PHP Security====<br />
By default, PHP processes are restricted to the specific <code>public/</code> directory. This is fine in normal use, but as the links created above are resolved to their targets, they don't match the paths expected and will cause PHP errors. As a workaround, creating the <code>config/disable-php-security</code> file for the new alias disables this restriction, slightly reducing the security of the sites.<br />
<br />
==Serving Content on an Alternate IP Address==<br />
<blockquote>Note that the IP addresses must be valid IPs allocated and routed to your server for this to function.</blockquote>By default, Sympl uses the primary IP addresses (both IPv4 and IPv6) to serve content on. To override this and serve content via another IP address, add the IPs to <code>/srv/'''''example.com'''''/config/ip</code>, followed by <code>sudo sympl-configure-ips</code> to automatically add the IP addresses to the relevant interface, and <code>sudo sympl-configure-ips</code> to adjust the apache configuration to use the new IPs, at which point you should update the DNS for the domain.<br />
<br />
==Hidden Files==<br />
{{Template:Sympl 12 Only}}<br />
By default, Sympl blocks any hidden files or directories (those with filenames that start with a dot, '<code>.</code>') from being served via the web, such as <code>.user.ini</code>, <code>.htaccess</code>, files in <code>.git</code> and so on.<br />
<br />
If needed, this can be turned off by creating the file <code>config/allow-hidden</code>, but when doing so you should ensure access to any sensitive files are restricted by <code>.htaccess</code>.<br />
<br />
==Enforcing HTTPS==<br />
By default, Sympl will attempt to download a [[Let's Encrypt]] [[SSL Certificate|SSL certificate]] for each site automatically, and will then adjust the Apache configuration to enable it.<br />
<br />
In many cases you will likely want to enforce HTTPS usage on a domain to ensure end-to-end security, and this can be done easily by creating the file <code>/srv/'''''example.com'''''/config/ssl-only</code>.<br />
<br />
This change will take effect automatically within the next hour, but requires a working certificate.<br />
<br />
===HTTP Strict Transport Security (HSTS)===<br />
Once SSL has been enforced, you may also want to ensure users only ever access the site via HTTPS. This can be done by enabling [[HTTP Strict Transport Security|HSTS]], which instructs the users browser to only connect via HTTPS for the next six months.<br />
<br />
You should ensure the site is working properly via HTTPS before enabling this function, but once done, create the file <code>/srv/'''''example.com'''''/config/hsts</code> and the configuration will be updated within the next hour.<br />
<br />
==Redirecting to a Preferred Domain==<br />
In the event you want to force all traffic to the same domain name, this can be done with an [[Apache Rewrites|Apache rewrite]]. This this example, we want to ensure the domain being used is always <code>www.'''''example.com'''''</code>, preventing anyone from using <code>'''''example.com'''''</code> without the <code>www.</code>.<br />
<br />
To do this, you would create a file named <code>.htaccess</code> in the <code>htdocs/</code> directory with this content:<br />
RewriteEngine on<br />
RewriteCond %{HTTP_HOST} !^www.*$ [NC]<br />
RewriteRule ^(.*)$ <nowiki>http://www.%{HTTP_HOST}/$1</nowiki> [R=302,L]<br />
What this set of rules do is:<br />
<br />
#Enable the rewriting of content.<br />
#If the hostname being used does not start with 'www.' (case insensitive)<br />
#Temporarily redirect the request to the same hostname but with 'www.' added and don't process any rules.<br />
<br />
Once this is working as expected, you can change the <code>R=302</code> to <code>R=301</code> to swap the temporary redirect to a permanent one which will be cached by the browser.<blockquote>More information is available at ''[[Apache Rewrites]]''.</blockquote><br />
<br />
<br />
<br />
==Filesystem Permissions==<br />
By default, Sympl adjusts the permissions of files and directories in <code>/srv/'''''example.com'''''/public</code> to ensure web applications can update themselves correctly, and FTP users can make changes as desired.<br />
<br />
This defaults to changing the files and directories to be readable, writable, and owned by the <code>www-data</code> user and the <code>www-data</code> group (which the <code>sympl</code> user is a member of). These defaults can be changed by placing the name or ID of the desired user and group into <code>config/public-user</code> and <code>config/public-group</code>.<br />
<br />
This functionality can be coupled with individual PHP instances for each site (not yet implemented in Sympl) or can be disabled on each domain by creating the file <code>/srv/'''''example.com'''''/config/disable-filesystem-security</code>.<blockquote>See ''[[Filesystem Security]]'' for more information.</blockquote><br />
<br />
==Logging==<br />
By default, the Apache logs are written to <code>/srv/'''''example.com'''''/public/logs</code>, named as either <code>access.log</code> and <code>error.log</code> for HTTP requests, and <code>ssl_access.log</code> and <code>ssl_error.log</code> for HTTPS.<br />
<br />
These are automatically rotated daily, and compressed after two days.<br />
<br />
For any sites being served with [[Mass Hosting|mass hosting]], the logs can be found at <code>/var/log/apache2/zz-mass-hosting.access.log</code> and <code>/var/log/apache2/zz-mass-hosting.error.log</code> .<br />
<br />
Logging for any other traffic is written to <code>/var/log/apache2/other_vhosts_access.log</code>, with any errors for Apache itself at <code>/var/log/apache2/error.log</code>.<br />
<br />
==Web Statistics==<br />
Basic traffic statistics can be optionally generated for the domain from the web logs using [[AWFFull]] (or [[Webalizer]] on Sympl 10 and older), and are written to <code>/srv/'''''example.com'''''/public/htdocs/stats</code>, making them available at <code>https://'''''example.com'''''/stats</code>. <br />
<br />
To trigger the generation, create a file at <code>/srv/'''''example.com'''''/config/stats</code>, and they will be generated automatically overnight for the previous day(s).<br />
<br />
As they contain potentially sensitive information (i.e. client IPs), they are automatically protected by a username and password. To access them you must create a username and password in <code>config/stats-htaccess</code> using <code>htpasswd</code>:<blockquote>'''Note:''' If the file already exists, you should omit the -c parameter or a fresh configuration file will be created and overwrite anything there.</blockquote><br />
htpasswd -c /srv/'''''example.com'''''/config/stats-htaccess '''''username'''''<br />
You will be prompted for a password and confirmation, and you will then be able to log in.<br />
<br />
A template for Webalizer will automatically be written to <code>config/webalizer.conf</code> when the statistics are created, and this can be edited as desired.<br />
<br />
==CGI Scripts==<br />
CGI Scripts are executable code of some kind (binaries or scripts) which are run directly on the operating system, and return the content for a page. Due to them being executable they can be a security risk, so caution should be taken when using them. Usage of CGI Scripts has mostly been supplanted by [[PHP]], however some legacy code <br />
<br />
To use CGI Scripts on your domain, you should copy them to <code>/srv/'''''example.com'''''/public/cgi-bin/</code> and they will then be served at <code>http://'''''example.com'''''/cgi-bin/</code> as long as the files are set executable. Non-executable files will result in an error message rather than serving the content of the file.<br />
<br />
Any files in the <code>public/cgi-bin</code> will not have their permissions updated by <code>sympl-filesystem-security</code>, so it is up to the user to ensure they are set securely, and readable only by the relevant users. Typically they are not be expected to be writable.<br />
<br />
==Custom Additions to the Apache Configuration==<br />
For sites with individual configuration files, custom additions can be made to the Apache configuration by adding files with the <code>.conf</code> extension to <code>/srv/'''''example.com'''''/conf/apache.d/</code>. These will be read when Apache is reloaded or started, and can be used to make changes to the configuration without using <code>.htaccess</code> files.<br />
<br />
The configuration can be tested with <code>sudo apachectl -t</code> and Apache reloaded with <code>sudo service apache2 reload</code>.<br />
<br />
Extreme care should be taken when using this feature, as an invalid configuration will prevent Apache from starting, as as such is considered a feature for advanced users only.<br />
<br />
==Further Modifying the Apache Configuration==<br />
The majority of typical changes to the Apache configuration can be made via relevant <code>.htaccess</code> files, with most of others available via <code>conf/apache.d/</code>.<br />
<br />
In the event you need to make custom changes to the Apache configuration for an individual site, configuration files can be found in <code>/etc/apache/sites-enabled</code>. Note that if you do make any changes, the configuration will no longer be managed by Sympl and it won't make any changes if the templates are updated. If you want to revert to a Sympl generated configuration for a specific domain, you can do this with <code>sudo sympl-web-configure --verbose '''''example.com'''''</code><br />
<br />
If you want to update the configuration of all sites, then you can edit the templates used to generate the Apache configurations, but you should take care when making any changes to ensure the result is valid. These can be found in <code>/etc/sympl/apache.d</code>, and the existing templated configurations can be regenerated with <code>sudo sympl-web-configure --verbose</code>. Note that any changes to the template files will prevent the templates from being automatically updated, pause updates to the <code>sympl-web</code> package until <br />
<br />
Finally, if you want to create your own Apache configurations not managed by Sympl you can do, as it will not make any changes to them.<br />
<br />
==Configuration Reference==<br />
<section begin="config" /><br />
{| class="wikitable sortable"<br />
|+<br />
!File or Directory<br />
!Used For<br />
!<br />
|-<br />
|<code>.../config/ip</code><br />
|Contains a list of IP addresses which a website will be bound to. Defaults to the primary IPs (IPv4 and IPv6) of your server.<br />
|[[Website Configuration Reference#Serving Content on an Alternate IP Address.|<small>More...</small>]]<br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/ssl-only</code><br />
|Redirects all non-HTTPS traffic for the site to HTTPS.<br />
|[[Website Configuration Reference#Enforcing HTTPS|<small>More...</small>]]<br />
|-<br />
|<code>.../config/hsts</code><br />
|Enables HSTS for HTTPS sites.<br />
|<small>[[Website Configuration Reference#HTTP Strict Transport Security (HSTS)|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/php</code><br />
|Selects the PHP version the site should be run under. Remove the file to default to the bundled version for your distribution.<br />
|<small>[[Website Configuration Reference#Selecting a PHP Version|More...]]</small><br />
|-<br />
|<code>.../config/php-modules</code><br />
|A list of PHP modules/extension package names for the site which will be installed automatically.<br />
|<small>[[Website Configuration Reference#Selecting a PHP Version|More...]]</small><br />
|-<br />
|<code>.../config/php-pool<br />
|Defines the alphanumeric name of the PHP pool for the site.<br />
|<small>[[Website Configuration Reference#Selecting a PHP Version|More...]]</small><br />
|-<br />
|<code>.../config/php-user</code><br />
|The local system user to run the PHP process as.<br />
|<small>[[Website Configuration Reference#Extended Configuration|More...]]</small><br />
|-<br />
|<code>.../config/php-group</code><br />
|The local group to run the PHP process as.<br />
|<small>[[Website Configuration Reference#Extended Configuration|More...]]</small><br />
|-<br />
|<code>.../config/disable-php-security</code><br />
|Existence of this file will disable some of the PHP security functions in the automatically generated [[Apache]] configurations.<br />
|<small>[[Website Configuration Reference#PHP Security|More...]]</small><br />
|-<br />
|<code>/etc/sympl/php/<version>/includes.d/<pool_name>.conf</code><br />
|Configuration changes for a specific PHP pool should be placed here.<br />
|<small>[[Website Configuration Reference#Extended Configuration|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/allow-hidden</code><br />
|Existence of this file will allow the website to serve files which are usually hidden.<br />
|<small>[[Website Configuration Reference#Hidden Files and Directories|More...]]</small><br />
|-<br />
|<code>.../config/disable-filesystem-security</code><br />
|Existence of this file will disable the automatic filesystem security tasks on this domain.<br />
|<small>[[Website Configuration Reference#Filesystem Permissions|More...]]</small><br />
|-<br />
|<code>.../config/public-user</code><br />
|UID or user name of the user to change ownership of the <code>public/</code> directory to. Defaults to www-data.<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
|<code>.../config/public-group</code><br />
|GID or group name of the user to change ownership of the <code>public/</code> directory to. Defaults to www-data.<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/stats</code><br />
|This file enables automatic generation of [[Web Statistics|web stats]] with [[Awffull]]/[[Webalizer]]<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
|<code>.../config/stats-htaccess</code><br />
|A '[[htpasswd]]' format file used to access the [[Web Statistics|web stats]].<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
|<code>.../config/apache.d/'''''example'''''.conf</code><br />
|Apache config files to be included in the site configuration.<br />
|<small>[[Website Configuration Reference#Custom Additions to the Apache Configuration|More...]]</small><br />
|}<section end="config" /><br />
<br />
<blockquote>See also [[Configuration Reference|''Configuration Reference'']] for other configuration files.</blockquote><br />
[[Category:Web]]<br />
[[Category:Reference]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Website_Configuration_Reference&diff=5017Website Configuration Reference2023-06-12T18:22:31Z<p>Kelduum: /* Serving Content on an Alternate IP Address */</p>
<hr />
<div>This page is a detailed breakdown of all the configuration options and files available when configuring website hosting on Sympl.<br />
<br />
As with all the other documentation here, the site <code>'''''example.com'''''</code> will used, and you should substitute this for your domain.<br />
<br />
All configuration for this domain will be in the /srv/example.com/ directory.<br />
<br />
Sympl uses the [[Apache]] web server, along with the relevant version of [[PHP]] for your version of [[Debian]], along with the typical PHP extensions. See [[Supported PHP Versions]].<br />
<br />
==Getting Started==<br />
The files for example.com are in the <code>/srv/'''''example.com'''''/public/htdocs</code> directory which is the site root.<br />
<br />
*If this directory doesn't exist, is empty, or has no <code>index.php</code> or <code>index.html</code>, the default page will be served, mentioning there is no content on the site.<br />
*The content in the directory will be served for both www.example.com and example.com, so theres no need to prefix the domain with www.<br />
*If you want to serve different content for www.example.com and example.com, you can create /srv/www.example.com as a separate directory.<br />
*Within an hour of the directory creation, a new configuration will [[Sympl-web-configure|automatically be created]] for Apache.<br />
<br />
More detailed information about how Sympl serves content can be found at ''[[How Web Hosting Works on Sympl]]''.<br />
<br />
==Testing Your Sites==<br />
New sites can be tested before they are made live using the 'testing' domains. If your hosting provider provides a wildcard DNS entry on your server pointing to its hostname (and the [[Default Site|default site]] is set to match), then sites can be accessed via this method.<br />
<br />
You can confirm if this is the case using <code>dig</code> or a similar tool - if your server is named <code>'''''server.example.host'''''</code>, if you run <code>dig +short randomname.'''''server.example.host'''''</code> and get a response with the server's IP address, then this is the case.<br />
<br />
If so, you can access any of the sites via this method in the format <domain_directory>.testing.<server_hostname>, for example <code>'''''example.com'''''.testing.'''''server.example.host'''''</code>. Note that the <code>www.</code> should not be included in this case.<br />
<br />
Note that this only applies to websites (not email, FTP and similar), and will not work fully in all instances, as some sites will redirect to their expected hostname or similar. If this is the case, you can test by [[Editing Your Hosts File|editing your hosts file]] on your local computer.<br />
<br />
== PHP Configuration ==<br />
<br />
PHP is the scripting language which the popular Content Management Systems and most websites is written in. It's very popular due to it's flexibility and ease of use, which means that the development of PHP moves quickly, with new versions released every year or so.<br />
<br />
With PHP development moving quickly, the Debian release cycle being every two years, and the common need to run sites on older versions, it's not uncommon to see an instance where you need a different version of PHP than the one bundled with the operating system.<br />
<br />
=== Selecting a PHP Version ===<br />
This isn't currently possible to do automatically on Sympl 11 and earlier, there are community-supported work-arounds. Sympl 12 adds support for selectable PHP versions, and this functionality is being back-ported to earlier versions.<br />
<br />
{{Template:Sympl 12 Only}}<br />
To select a PHP version for a specific site, place the PHP major and minor versions (such as '5.6', '7.3' or '8.1') in the file <code>config/php</code> and run <code>sudo sympl-php-configure</code>.<br />
<br />
This will then install the relevant PHP version from [https://deb.sury.org https://deb.sury.org] if required, along with the typical PHP packages, and configure the site to use that PHP version. Note there is a small extra disk space requirement for each extra version of PHP installed.<br />
<br />
If other PHP modules/extensions are required for the site, their package names can be placed in <code>config/php-modules</code>, and they will be installed automatically the next time <code>sudo sympl-php-configure</code> is run. Package names are the name of the Debian packaged modules without the PHP version, so the <code>php8.1-tidy</code> package would be listed in the file as <code>tidy</code>. PHP extensions can also be installed manually using apt.<br />
<br />
All sites default to a pool named 'default' unless specified otherwise in <code>config/php-pool</code>. If you require any configuration changes, or wish to adjust resources for a site, you should configure it with it's own pool. Note that each pool has its own memory requirements and PHP instances standing by, so running a large number of pools will consume more RAM on your server.<br />
<br />
=== .htaccess vs .user.ini ===<br />
{{Template:Sympl 12 Only}}<br />
When using the default PHP version (ie: not specifying one) the site will run under the default PHP version for the distribution (ie: PHP 8.2 for Debian Bookworm) using 'mod_apache'. This will parse PHP variables and overrides via the <code>.htaccess</code> file in the web content directory, allowing you to make changes on a per-directory basis.<br />
<br />
Running a site under 'FPM' as the configured sites do means they are only passed the relevant file, so require the same configuration entries in a slightly different format in the file <code>.user.ini</code> file, in the same location as <code>.htaccess</code>.<br />
<br />
If you don't already have a <code>.user.ini</code> file in place, Sympl will automatically create and manage one for you each time <code>sudo sympl-php-configure</code> is run. <br />
<br />
=== PHP Command Line ===<br />
{{Template:Sympl 12 Only}}<br />
In some instances, you may need to run the PHP from the command line but need a version other than the default. To do so, rather than using the plain <code>php example.php</code> command, simply append the version, for example <code>php8.1 example.php</code>.<br />
<br />
=== Extended Configuration ===<br />
{{Template:Sympl 12 Only}}<br />
Sympl supports a number of other extended configuration options, including selectable user and group that the PHP pool should be executed as, with <code>config/php-user</code> and <code>config/php-group</code> respectively. These default to www-data, but if must exist if they are changed, and cannot be system users (ie: with an ID below 1000). Note that these settings also inherit the values of <code>public-user</code> and <code>public-group</code> if set.<br />
<br />
As the PHP pool files are managed automatically by Sympl to ensure that PHP continues running, manual changes to the pool configurations will be overwritten on each run. If a change to a pool configuration is required, extra configuration lines can be added to <code>/etc/sympl/php/<version>/includes.d/<pool_name>.conf</code>. The pool name is defined as <code><pool_name>[_<username>[_<groupname>]]</code> with the username and group being optional if not left on the default.<br />
<br />
===PHP Security===<br />
By default, a number of rules are included in the Apache configuration which limit the access of sites running PHP, preventing a compromised site from accessing content outside the <code>/srv/example.com/public/</code> directory, and setting both a domain-specific temp directory and session directory as <code>/srv/example.com/php_tmp/</code> and <code>/srv/example.com/php_sessions/</code> respectively.<br />
<br />
A default configuration is also in place for the ever-popular [[WordPress]], which prevents PHP files from being accessed or executed from within the upload folder, which tend to be the source of most site compromises.<br />
<br />
These restrictions can be disabled by creating the file <code>/srv/example.com/config/disable-php-security</code>, and running <code>sudo sympl-web-configure</code>.<br />
<br />
====PHP Lockdown====<br />
Also available but not enabled by default is a '[[PHP Lockdown|lockdown]]' configuration, which limits a number of potentially dangerous functions in PHP for ''all sites'' where a PHP version is not selected.<br />
<br />
This can be enabled with the command line...<br />
<br />
'''For Sympl 10.x'''<br />
sudo ln -s /etc/php/7.0/mods-available/sympl-web-lockdown.ini /etc/php/7.0/apache2/conf.d/01-sympl-web-lockdown.ini<br />
sudo service apache2 reload<br />
'''For Sympl 11.x'''<br />
sudo ln -s /etc/php/7.3/mods-available/sympl-web-lockdown.ini /etc/php/7.3/apache2/conf.d/01-sympl-web-lockdown.ini<br />
sudo service apache2 reload<br />
'''For Sympl 12.x'''<br />
sudo ln -s /etc/php/8.2/mods-available/sympl-web-lockdown.ini /etc/php/8.2/apache2/conf.d/01-sympl-web-lockdown.ini<br />
sudo service apache2 reload<br />
<br />
Note that this will significantly restrict PHP access, and will affect all sites on the same server, so you should confirm that all sites work as expected once this has been run.<br />
<br />
==Serving the Same Content on Multiple Domains.==<br />
In some cases you may want to accept traffic for and serve the same content for multiple domains, such as [[WordPress Multi-site|WordPress multi-site]] configurations.<br />
<br />
Both of these assume you have the main site already configured and working.<br />
<br />
===Aliasing the Whole Domain===<br />
The most simple option is to alias the whole domain. This will result in the whole configuration including other services such as email, SSL certificates, and FTP sites all sharing the same domain.<br />
<br />
To do this, you only need to create a [[Symbolic Link|symbolic link]] to the directory of the site you want to alias. Aliasing <code>'''''example.org'''''</code> (new domain) to <code>'''''example.com'''''</code> (existing domain) you would use<br />
ln -s /srv/'''''example.com''''' /srv/'''''example.org'''''<br />
<br />
===Aliasing the Web Content Only===<br />
Slightly more complicated, but more flexible is to alias only the <code>public/</code> or <code>public/htdocs/</code> directory. This allows separate email, SSL certificates and individual, which don't reference the main domain. Some sites access content at the directory above <code>htdocs/</code>, in which case you should link at the <code>public/</code> point, otherwise <code>public/htdocs/</code> is usually preferable as it provides separate logging and allows individual FTP access.<br />
<br />
In the examples below, <code>example.com</code> is the site which already exists, and <code>example.org</code> is the new domain.<br />
<br />
====Aliasing public/htdocs/ Only====<br />
mkdir -p /srv/example.org/public<br />
ln -s /srv/example.com/public/htdocs /srv/example.org/public/htdocs<br />
touch /srv/example.org/config/disable-php-security<br />
<br />
====Aliassing public/ and Subdirectories====<br />
mkdir -p /srv/example.org<br />
ln -s /srv/example.com/public /srv/example.org/public<br />
touch /srv/example.org/config/disable-php-security<br />
<br />
====A Note on PHP Security====<br />
By default, PHP processes are restricted to the specific <code>public/</code> directory. This is fine in normal use, but as the links created above are resolved to their targets, they don't match the paths expected and will cause PHP errors. As a workaround, creating the <code>config/disable-php-security</code> file for the new alias disables this restriction, slightly reducing the security of the sites.<br />
<br />
==Serving Content on an Alternate IP Address==<br />
<blockquote>Note that the IP addresses must be valid IPs allocated and routed to your server for this to function.</blockquote>By default, Sympl uses the primary IP addresses (both IPv4 and IPv6) to serve content on. To override this and serve content via another IP address, add the IPs to <code>/srv/'''''example.com'''''/config/ip</code>, followed by <code>sudo sympl-configure-ips</code> to automatically add the IP addresses to the relevant interface, and <code>sudo sympl-configure-ips</code> to adjust the apache configuration to use the new IPs, at which point you should update the DNS for the domain.<br />
<br />
==Hidden Files==<br />
{{Template:Sympl 12 Only}}<br />
By default, Sympl blocks any hidden files or directories (those with filenames that start with a dot, '<code>.</code>') from being served via the web, such as <code>.user.ini</code>, <code>.htaccess</code>, files in <code>.git</code> and so on.<br />
<br />
If needed, this can be turned off by creating the file <code>config/allow-hidden</code>, but when doing so you should ensure access to any sensitive files are restricted by <code>.htaccess</code>.<br />
<br />
==Enforcing HTTPS==<br />
By default, Sympl will attempt to download a [[Let's Encrypt]] [[SSL Certificate|SSL certificate]] for each site automatically, and will then adjust the Apache configuration to enable it.<br />
<br />
In many cases you will likely want to enforce HTTPS usage on a domain to ensure end-to-end security, and this can be done easily by creating the file <code>/srv/'''''example.com'''''/config/ssl-only</code>.<br />
<br />
This change will take effect automatically within the next hour, but requires a working certificate.<br />
<br />
===HTTP Strict Transport Security (HSTS)===<br />
Once SSL has been enforced, you may also want to ensure users only ever access the site via HTTPS. This can be done by enabling [[HTTP Strict Transport Security|HSTS]], which instructs the users browser to only connect via HTTPS for the next six months.<br />
<br />
You should ensure the site is working properly via HTTPS before enabling this function, but once done, create the file <code>/srv/'''''example.com'''''/config/hsts</code> and the configuration will be updated within the next hour.<br />
<br />
==Redirecting to a Preferred Domain==<br />
In the event you want to force all traffic to the same domain name, this can be done with an [[Apache Rewrites|Apache rewrite]]. This this example, we want to ensure the domain being used is always <code>www.'''''example.com'''''</code>, preventing anyone from using <code>'''''example.com'''''</code> without the <code>www.</code>.<br />
<br />
To do this, you would create a file named <code>.htaccess</code> in the <code>htdocs/</code> directory with this content:<br />
RewriteEngine on<br />
RewriteCond %{HTTP_HOST} !^www.*$ [NC]<br />
RewriteRule ^(.*)$ <nowiki>http://www.%{HTTP_HOST}/$1</nowiki> [R=302,L]<br />
What this set of rules do is:<br />
<br />
#Enable the rewriting of content.<br />
#If the hostname being used does not start with 'www.' (case insensitive)<br />
#Temporarily redirect the request to the same hostname but with 'www.' added and don't process any rules.<br />
<br />
Once this is working as expected, you can change the <code>R=302</code> to <code>R=301</code> to swap the temporary redirect to a permanent one which will be cached by the browser.<blockquote>More information is available at ''[[Apache Rewrites]]''.</blockquote><br />
<br />
<br />
<br />
==Filesystem Permissions==<br />
By default, Sympl adjusts the permissions of files and directories in <code>/srv/'''''example.com'''''/public</code> to ensure web applications can update themselves correctly, and FTP users can make changes as desired.<br />
<br />
This defaults to changing the files and directories to be readable, writable, and owned by the <code>www-data</code> user and the <code>www-data</code> group (which the <code>sympl</code> user is a member of). These defaults can be changed by placing the name or ID of the desired user and group into <code>config/public-user</code> and <code>config/public-group</code>.<br />
<br />
This functionality can be coupled with individual PHP instances for each site (not yet implemented in Sympl) or can be disabled on each domain by creating the file <code>/srv/'''''example.com'''''/config/disable-filesystem-security</code>.<blockquote>See ''[[Filesystem Security]]'' for more information.</blockquote><br />
<br />
==Logging==<br />
By default, the Apache logs are written to <code>/srv/'''''example.com'''''/public/logs</code>, named as either <code>access.log</code> and <code>error.log</code> for HTTP requests, and <code>ssl_access.log</code> and <code>ssl_error.log</code> for HTTPS.<br />
<br />
These are automatically rotated daily, and compressed after two days.<br />
<br />
For any sites being served with [[Mass Hosting|mass hosting]], the logs can be found at <code>/var/log/apache2/zz-mass-hosting.access.log</code> and <code>/var/log/apache2/zz-mass-hosting.error.log</code> .<br />
<br />
Logging for any other traffic is written to <code>/var/log/apache2/other_vhosts_access.log</code>, with any errors for Apache itself at <code>/var/log/apache2/error.log</code>.<br />
<br />
==Web Statistics==<br />
Basic traffic statistics can be optionally generated for the domain from the web logs using [[AWFFull]] (or [[Webalizer]] on Sympl 10 and older), and are written to <code>/srv/'''''example.com'''''/public/htdocs/stats</code>, making them available at <code>https://'''''example.com'''''/stats</code>. <br />
<br />
To trigger the generation, create a file at <code>/srv/'''''example.com'''''/config/stats</code>, and they will be generated automatically overnight for the previous day(s).<br />
<br />
As they contain potentially sensitive information (i.e. client IPs), they are automatically protected by a username and password. To access them you must create a username and password in <code>config/stats-htaccess</code> using <code>htpasswd</code>:<blockquote>'''Note:''' If the file already exists, you should omit the -c parameter or a fresh configuration file will be created and overwrite anything there.</blockquote><br />
htpasswd -c /srv/'''''example.com'''''/config/stats-htaccess '''''username'''''<br />
You will be prompted for a password and confirmation, and you will then be able to log in.<br />
<br />
A template for Webalizer will automatically be written to <code>config/webalizer.conf</code> when the statistics are created, and this can be edited as desired.<br />
<br />
==CGI Scripts==<br />
CGI Scripts are executable code of some kind (binaries or scripts) which are run directly on the operating system, and return the content for a page. Due to them being executable they can be a security risk, so caution should be taken when using them. Usage of CGI Scripts has mostly been supplanted by [[PHP]], however some legacy code <br />
<br />
To use CGI Scripts on your domain, you should copy them to <code>/srv/'''''example.com'''''/public/cgi-bin/</code> and they will then be served at <code>http://'''''example.com'''''/cgi-bin/</code> as long as the files are set executable. Non-executable files will result in an error message rather than serving the content of the file.<br />
<br />
Any files in the <code>public/cgi-bin</code> will not have their permissions updated by <code>sympl-filesystem-security</code>, so it is up to the user to ensure they are set securely, and readable only by the relevant users. Typically they are not be expected to be writable.<br />
<br />
==Custom Additions to the Apache Configuration==<br />
For sites with individual configuration files, custom additions can be made to the Apache configuration by adding files with the <code>.conf</code> extension to <code>/srv/'''''example.com'''''/conf/apache.d/</code>. These will be read when Apache is reloaded or started, and can be used to make changes to the configuration without using <code>.htaccess</code> files.<br />
<br />
The configuration can be tested with <code>sudo apachectl -t</code> and Apache reloaded with <code>sudo service apache2 reload</code>.<br />
<br />
Extreme care should be taken when using this feature, as an invalid configuration will prevent Apache from starting, as as such is considered a feature for advanced users only.<br />
<br />
==Further Modifying the Apache Configuration==<br />
The majority of typical changes to the Apache configuration can be made via relevant <code>.htaccess</code> files, with most of others available via <code>conf/apache.d/</code>.<br />
<br />
In the event you need to make custom changes to the Apache configuration for an individual site, configuration files can be found in <code>/etc/apache/sites-enabled</code>. Note that if you do make any changes, the configuration will no longer be managed by Sympl and it won't make any changes if the templates are updated. If you want to revert to a Sympl generated configuration for a specific domain, you can do this with <code>sudo sympl-web-configure --verbose '''''example.com'''''</code><br />
<br />
If you want to update the configuration of all sites, then you can edit the templates used to generate the Apache configurations, but you should take care when making any changes to ensure the result is valid. These can be found in <code>/etc/sympl/apache.d</code>, and the existing templated configurations can be regenerated with <code>sudo sympl-web-configure --verbose</code>. Note that any changes to the template files will prevent the templates from being automatically updated, pause updates to the <code>sympl-web</code> package until <br />
<br />
Finally, if you want to create your own Apache configurations not managed by Sympl you can do, as it will not make any changes to them.<br />
<br />
==Configuration Reference==<br />
<section begin="config" /><br />
{| class="wikitable sortable"<br />
|+<br />
!File or Directory<br />
!Used For<br />
!<br />
|-<br />
|<code>.../config/ip</code><br />
|Contains a list of IP addresses which a website will be bound to. Defaults to the primary IPs (IPv4 and IPv6) of your server.<br />
|[[Website Configuration Reference#Serving Content on an Alternate IP Address.|<small>More...</small>]]<br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/ssl-only</code><br />
|Redirects all non-HTTPS traffic for the site to HTTPS.<br />
|[[Website Configuration Reference#Enforcing HTTPS|<small>More...</small>]]<br />
|-<br />
|<code>.../config/hsts</code><br />
|Enables HSTS for HTTPS sites.<br />
|<small>[[Website Configuration Reference#HTTP Strict Transport Security (HSTS)|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/php</code><br />
|Selects the PHP version the site should be run under. Remove the file to default to the bundled version for your distribution.<br />
|<small>[[Website Configuration Reference#Selecting a PHP Version|More...]]</small><br />
|-<br />
|<code>.../config/php-modules</code><br />
|A list of PHP modules/extension package names for the site which will be installed automatically.<br />
|<small>[[Website Configuration Reference#Selecting a PHP Version|More...]]</small><br />
|-<br />
|<code>.../config/php-pool<br />
|Defines the alphanumeric name of the PHP pool for the site.<br />
|<small>[[Website Configuration Reference#Selecting a PHP Version|More...]]</small><br />
|-<br />
|<code>.../config/php-user</code><br />
|The local system user to run PHP as<br />
|<small>[[Website Configuration Reference#Extended Configuration|More...]]</small><br />
|-<br />
|<code>.../config/php-group</code><br />
|The local group to run PHP as.<br />
|<small>[[Website Configuration Reference#Extended Configuration|More...]]</small><br />
|-<br />
|<code>.../config/disable-php-security</code><br />
|Existence of this file will disable some of the PHP security functions in the automatically generated [[Apache]] configurations.<br />
|<small>[[Website Configuration Reference#PHP Security|More...]]</small><br />
|-<br />
|<code>/etc/sympl/php/<version>/includes.d/<pool_name>.conf</code><br />
|Configuration changes for a specific PHP pool should be placed here.<br />
|<small>[[Website Configuration Reference#Extended Configuration|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/disable-filesystem-security</code><br />
|Existence of this file will disable the automatic filesystem security tasks on this domain.<br />
|<small>[[Website Configuration Reference#Filesystem Permissions|More...]]</small><br />
|-<br />
|<code>.../config/public-user</code><br />
|UID or user name of the user to change ownership of the <code>public/</code> directory to. Defaults to www-data.<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
|<code>.../config/public-group</code><br />
|GID or group name of the user to change ownership of the <code>public/</code> directory to. Defaults to www-data.<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/stats</code><br />
|This file enables automatic generation of [[Web Statistics|web stats]] with [[Awffull]]/[[Webalizer]]<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
|<code>.../config/stats-htaccess</code><br />
|A '[[htpasswd]]' format file used to access the [[Web Statistics|web stats]].<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
|<code>.../config/apache.d/'''''example'''''.conf</code><br />
|Apache config files to be included in the site configuration.<br />
|<small>[[Website Configuration Reference#Custom Additions to the Apache Configuration|More...]]</small><br />
|}<section end="config" /><br />
<br />
<blockquote>See also [[Configuration Reference|''Configuration Reference'']] for other configuration files.</blockquote><br />
[[Category:Web]]<br />
[[Category:Reference]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Website_Configuration_Reference&diff=5016Website Configuration Reference2023-06-12T17:23:27Z<p>Kelduum: /* Extended Configuration */</p>
<hr />
<div>This page is a detailed breakdown of all the configuration options and files available when configuring website hosting on Sympl.<br />
<br />
As with all the other documentation here, the site <code>'''''example.com'''''</code> will used, and you should substitute this for your domain.<br />
<br />
All configuration for this domain will be in the /srv/example.com/ directory.<br />
<br />
Sympl uses the [[Apache]] web server, along with the relevant version of [[PHP]] for your version of [[Debian]], along with the typical PHP extensions. See [[Supported PHP Versions]].<br />
<br />
==Getting Started==<br />
The files for example.com are in the <code>/srv/'''''example.com'''''/public/htdocs</code> directory which is the site root.<br />
<br />
*If this directory doesn't exist, is empty, or has no <code>index.php</code> or <code>index.html</code>, the default page will be served, mentioning there is no content on the site.<br />
*The content in the directory will be served for both www.example.com and example.com, so theres no need to prefix the domain with www.<br />
*If you want to serve different content for www.example.com and example.com, you can create /srv/www.example.com as a separate directory.<br />
*Within an hour of the directory creation, a new configuration will [[Sympl-web-configure|automatically be created]] for Apache.<br />
<br />
More detailed information about how Sympl serves content can be found at ''[[How Web Hosting Works on Sympl]]''.<br />
<br />
==Testing Your Sites==<br />
New sites can be tested before they are made live using the 'testing' domains. If your hosting provider provides a wildcard DNS entry on your server pointing to its hostname (and the [[Default Site|default site]] is set to match), then sites can be accessed via this method.<br />
<br />
You can confirm if this is the case using <code>dig</code> or a similar tool - if your server is named <code>'''''server.example.host'''''</code>, if you run <code>dig +short randomname.'''''server.example.host'''''</code> and get a response with the server's IP address, then this is the case.<br />
<br />
If so, you can access any of the sites via this method in the format <domain_directory>.testing.<server_hostname>, for example <code>'''''example.com'''''.testing.'''''server.example.host'''''</code>. Note that the <code>www.</code> should not be included in this case.<br />
<br />
Note that this only applies to websites (not email, FTP and similar), and will not work fully in all instances, as some sites will redirect to their expected hostname or similar. If this is the case, you can test by [[Editing Your Hosts File|editing your hosts file]] on your local computer.<br />
<br />
== PHP Configuration ==<br />
<br />
PHP is the scripting language which the popular Content Management Systems and most websites is written in. It's very popular due to it's flexibility and ease of use, which means that the development of PHP moves quickly, with new versions released every year or so.<br />
<br />
With PHP development moving quickly, the Debian release cycle being every two years, and the common need to run sites on older versions, it's not uncommon to see an instance where you need a different version of PHP than the one bundled with the operating system.<br />
<br />
=== Selecting a PHP Version ===<br />
This isn't currently possible to do automatically on Sympl 11 and earlier, there are community-supported work-arounds. Sympl 12 adds support for selectable PHP versions, and this functionality is being back-ported to earlier versions.<br />
<br />
{{Template:Sympl 12 Only}}<br />
To select a PHP version for a specific site, place the PHP major and minor versions (such as '5.6', '7.3' or '8.1') in the file <code>config/php</code> and run <code>sudo sympl-php-configure</code>.<br />
<br />
This will then install the relevant PHP version from [https://deb.sury.org https://deb.sury.org] if required, along with the typical PHP packages, and configure the site to use that PHP version. Note there is a small extra disk space requirement for each extra version of PHP installed.<br />
<br />
If other PHP modules/extensions are required for the site, their package names can be placed in <code>config/php-modules</code>, and they will be installed automatically the next time <code>sudo sympl-php-configure</code> is run. Package names are the name of the Debian packaged modules without the PHP version, so the <code>php8.1-tidy</code> package would be listed in the file as <code>tidy</code>. PHP extensions can also be installed manually using apt.<br />
<br />
All sites default to a pool named 'default' unless specified otherwise in <code>config/php-pool</code>. If you require any configuration changes, or wish to adjust resources for a site, you should configure it with it's own pool. Note that each pool has its own memory requirements and PHP instances standing by, so running a large number of pools will consume more RAM on your server.<br />
<br />
=== .htaccess vs .user.ini ===<br />
{{Template:Sympl 12 Only}}<br />
When using the default PHP version (ie: not specifying one) the site will run under the default PHP version for the distribution (ie: PHP 8.2 for Debian Bookworm) using 'mod_apache'. This will parse PHP variables and overrides via the <code>.htaccess</code> file in the web content directory, allowing you to make changes on a per-directory basis.<br />
<br />
Running a site under 'FPM' as the configured sites do means they are only passed the relevant file, so require the same configuration entries in a slightly different format in the file <code>.user.ini</code> file, in the same location as <code>.htaccess</code>.<br />
<br />
If you don't already have a <code>.user.ini</code> file in place, Sympl will automatically create and manage one for you each time <code>sudo sympl-php-configure</code> is run. <br />
<br />
=== PHP Command Line ===<br />
{{Template:Sympl 12 Only}}<br />
In some instances, you may need to run the PHP from the command line but need a version other than the default. To do so, rather than using the plain <code>php example.php</code> command, simply append the version, for example <code>php8.1 example.php</code>.<br />
<br />
=== Extended Configuration ===<br />
{{Template:Sympl 12 Only}}<br />
Sympl supports a number of other extended configuration options, including selectable user and group that the PHP pool should be executed as, with <code>config/php-user</code> and <code>config/php-group</code> respectively. These default to www-data, but if must exist if they are changed, and cannot be system users (ie: with an ID below 1000). Note that these settings also inherit the values of <code>public-user</code> and <code>public-group</code> if set.<br />
<br />
As the PHP pool files are managed automatically by Sympl to ensure that PHP continues running, manual changes to the pool configurations will be overwritten on each run. If a change to a pool configuration is required, extra configuration lines can be added to <code>/etc/sympl/php/<version>/includes.d/<pool_name>.conf</code>. The pool name is defined as <code><pool_name>[_<username>[_<groupname>]]</code> with the username and group being optional if not left on the default.<br />
<br />
===PHP Security===<br />
By default, a number of rules are included in the Apache configuration which limit the access of sites running PHP, preventing a compromised site from accessing content outside the <code>/srv/example.com/public/</code> directory, and setting both a domain-specific temp directory and session directory as <code>/srv/example.com/php_tmp/</code> and <code>/srv/example.com/php_sessions/</code> respectively.<br />
<br />
A default configuration is also in place for the ever-popular [[WordPress]], which prevents PHP files from being accessed or executed from within the upload folder, which tend to be the source of most site compromises.<br />
<br />
These restrictions can be disabled by creating the file <code>/srv/example.com/config/disable-php-security</code>, and running <code>sudo sympl-web-configure</code>.<br />
<br />
====PHP Lockdown====<br />
Also available but not enabled by default is a '[[PHP Lockdown|lockdown]]' configuration, which limits a number of potentially dangerous functions in PHP for ''all sites'' where a PHP version is not selected.<br />
<br />
This can be enabled with the command line...<br />
<br />
'''For Sympl 10.x'''<br />
sudo ln -s /etc/php/7.0/mods-available/sympl-web-lockdown.ini /etc/php/7.0/apache2/conf.d/01-sympl-web-lockdown.ini<br />
sudo service apache2 reload<br />
'''For Sympl 11.x'''<br />
sudo ln -s /etc/php/7.3/mods-available/sympl-web-lockdown.ini /etc/php/7.3/apache2/conf.d/01-sympl-web-lockdown.ini<br />
sudo service apache2 reload<br />
'''For Sympl 12.x'''<br />
sudo ln -s /etc/php/8.2/mods-available/sympl-web-lockdown.ini /etc/php/8.2/apache2/conf.d/01-sympl-web-lockdown.ini<br />
sudo service apache2 reload<br />
<br />
Note that this will significantly restrict PHP access, and will affect all sites on the same server, so you should confirm that all sites work as expected once this has been run.<br />
<br />
==Serving the Same Content on Multiple Domains.==<br />
In some cases you may want to accept traffic for and serve the same content for multiple domains, such as [[WordPress Multi-site|WordPress multi-site]] configurations.<br />
<br />
Both of these assume you have the main site already configured and working.<br />
<br />
===Aliasing the Whole Domain===<br />
The most simple option is to alias the whole domain. This will result in the whole configuration including other services such as email, SSL certificates, and FTP sites all sharing the same domain.<br />
<br />
To do this, you only need to create a [[Symbolic Link|symbolic link]] to the directory of the site you want to alias. Aliasing <code>'''''example.org'''''</code> (new domain) to <code>'''''example.com'''''</code> (existing domain) you would use<br />
ln -s /srv/'''''example.com''''' /srv/'''''example.org'''''<br />
<br />
===Aliasing the Web Content Only===<br />
Slightly more complicated, but more flexible is to alias only the <code>public/</code> or <code>public/htdocs/</code> directory. This allows separate email, SSL certificates and individual, which don't reference the main domain. Some sites access content at the directory above <code>htdocs/</code>, in which case you should link at the <code>public/</code> point, otherwise <code>public/htdocs/</code> is usually preferable as it provides separate logging and allows individual FTP access.<br />
<br />
In the examples below, <code>example.com</code> is the site which already exists, and <code>example.org</code> is the new domain.<br />
<br />
====Aliasing public/htdocs/ Only====<br />
mkdir -p /srv/example.org/public<br />
ln -s /srv/example.com/public/htdocs /srv/example.org/public/htdocs<br />
touch /srv/example.org/config/disable-php-security<br />
<br />
====Aliassing public/ and Subdirectories====<br />
mkdir -p /srv/example.org<br />
ln -s /srv/example.com/public /srv/example.org/public<br />
touch /srv/example.org/config/disable-php-security<br />
<br />
====A Note on PHP Security====<br />
By default, PHP processes are restricted to the specific <code>public/</code> directory. This is fine in normal use, but as the links created above are resolved to their targets, they don't match the paths expected and will cause PHP errors. As a workaround, creating the <code>config/disable-php-security</code> file for the new alias disables this restriction, slightly reducing the security of the sites.<br />
<br />
==Serving Content on an Alternate IP Address==<br />
<blockquote>Note that the IP addresses must be valid IPs allocated and routed to your server for this to function.</blockquote>By default, Sympl uses the primary IP addresses (both IPv4 and IPv6) to serve content on. To override this and serve content via another IP address, add the IPs to <code>/srv/'''''example.com'''''/config/ip</code>, followed by <code>sudo sympl-configure-ips</code> to automatically add the IP addresses to the relevant interface, and <code>sudo sympl-configure-ips</code> to adjust the apache configuration to use the new IPs, at which point you should update the DNS for the domain.<br />
<br />
==Enforcing HTTPS==<br />
By default, Sympl will attempt to download a [[Let's Encrypt]] [[SSL Certificate|SSL certificate]] for each site automatically, and will then adjust the Apache configuration to enable it.<br />
<br />
In many cases you will likely want to enforce HTTPS usage on a domain to ensure end-to-end security, and this can be done easily by creating the file <code>/srv/'''''example.com'''''/config/ssl-only</code>.<br />
<br />
This change will take effect automatically within the next hour, but requires a working certificate.<br />
<br />
===HTTP Strict Transport Security (HSTS)===<br />
Once SSL has been enforced, you may also want to ensure users only ever access the site via HTTPS. This can be done by enabling [[HTTP Strict Transport Security|HSTS]], which instructs the users browser to only connect via HTTPS for the next six months.<br />
<br />
You should ensure the site is working properly via HTTPS before enabling this function, but once done, create the file <code>/srv/'''''example.com'''''/config/hsts</code> and the configuration will be updated within the next hour.<br />
<br />
==Redirecting to a Preferred Domain==<br />
In the event you want to force all traffic to the same domain name, this can be done with an [[Apache Rewrites|Apache rewrite]]. This this example, we want to ensure the domain being used is always <code>www.'''''example.com'''''</code>, preventing anyone from using <code>'''''example.com'''''</code> without the <code>www.</code>.<br />
<br />
To do this, you would create a file named <code>.htaccess</code> in the <code>htdocs/</code> directory with this content:<br />
RewriteEngine on<br />
RewriteCond %{HTTP_HOST} !^www.*$ [NC]<br />
RewriteRule ^(.*)$ <nowiki>http://www.%{HTTP_HOST}/$1</nowiki> [R=302,L]<br />
What this set of rules do is:<br />
<br />
#Enable the rewriting of content.<br />
#If the hostname being used does not start with 'www.' (case insensitive)<br />
#Temporarily redirect the request to the same hostname but with 'www.' added and don't process any rules.<br />
<br />
Once this is working as expected, you can change the <code>R=302</code> to <code>R=301</code> to swap the temporary redirect to a permanent one which will be cached by the browser.<blockquote>More information is available at ''[[Apache Rewrites]]''.</blockquote><br />
<br />
<br />
<br />
==Filesystem Permissions==<br />
By default, Sympl adjusts the permissions of files and directories in <code>/srv/'''''example.com'''''/public</code> to ensure web applications can update themselves correctly, and FTP users can make changes as desired.<br />
<br />
This defaults to changing the files and directories to be readable, writable, and owned by the <code>www-data</code> user and the <code>www-data</code> group (which the <code>sympl</code> user is a member of). These defaults can be changed by placing the name or ID of the desired user and group into <code>config/public-user</code> and <code>config/public-group</code>.<br />
<br />
This functionality can be coupled with individual PHP instances for each site (not yet implemented in Sympl) or can be disabled on each domain by creating the file <code>/srv/'''''example.com'''''/config/disable-filesystem-security</code>.<blockquote>See ''[[Filesystem Security]]'' for more information.</blockquote><br />
<br />
==Logging==<br />
By default, the Apache logs are written to <code>/srv/'''''example.com'''''/public/logs</code>, named as either <code>access.log</code> and <code>error.log</code> for HTTP requests, and <code>ssl_access.log</code> and <code>ssl_error.log</code> for HTTPS.<br />
<br />
These are automatically rotated daily, and compressed after two days.<br />
<br />
For any sites being served with [[Mass Hosting|mass hosting]], the logs can be found at <code>/var/log/apache2/zz-mass-hosting.access.log</code> and <code>/var/log/apache2/zz-mass-hosting.error.log</code> .<br />
<br />
Logging for any other traffic is written to <code>/var/log/apache2/other_vhosts_access.log</code>, with any errors for Apache itself at <code>/var/log/apache2/error.log</code>.<br />
<br />
==Web Statistics==<br />
Basic traffic statistics can be optionally generated for the domain from the web logs using [[AWFFull]] (or [[Webalizer]] on Sympl 10 and older), and are written to <code>/srv/'''''example.com'''''/public/htdocs/stats</code>, making them available at <code>https://'''''example.com'''''/stats</code>. <br />
<br />
To trigger the generation, create a file at <code>/srv/'''''example.com'''''/config/stats</code>, and they will be generated automatically overnight for the previous day(s).<br />
<br />
As they contain potentially sensitive information (i.e. client IPs), they are automatically protected by a username and password. To access them you must create a username and password in <code>config/stats-htaccess</code> using <code>htpasswd</code>:<blockquote>'''Note:''' If the file already exists, you should omit the -c parameter or a fresh configuration file will be created and overwrite anything there.</blockquote><br />
htpasswd -c /srv/'''''example.com'''''/config/stats-htaccess '''''username'''''<br />
You will be prompted for a password and confirmation, and you will then be able to log in.<br />
<br />
A template for Webalizer will automatically be written to <code>config/webalizer.conf</code> when the statistics are created, and this can be edited as desired.<br />
<br />
==CGI Scripts==<br />
CGI Scripts are executable code of some kind (binaries or scripts) which are run directly on the operating system, and return the content for a page. Due to them being executable they can be a security risk, so caution should be taken when using them. Usage of CGI Scripts has mostly been supplanted by [[PHP]], however some legacy code <br />
<br />
To use CGI Scripts on your domain, you should copy them to <code>/srv/'''''example.com'''''/public/cgi-bin/</code> and they will then be served at <code>http://'''''example.com'''''/cgi-bin/</code> as long as the files are set executable. Non-executable files will result in an error message rather than serving the content of the file.<br />
<br />
Any files in the <code>public/cgi-bin</code> will not have their permissions updated by <code>sympl-filesystem-security</code>, so it is up to the user to ensure they are set securely, and readable only by the relevant users. Typically they are not be expected to be writable.<br />
<br />
==Custom Additions to the Apache Configuration==<br />
For sites with individual configuration files, custom additions can be made to the Apache configuration by adding files with the <code>.conf</code> extension to <code>/srv/'''''example.com'''''/conf/apache.d/</code>. These will be read when Apache is reloaded or started, and can be used to make changes to the configuration without using <code>.htaccess</code> files.<br />
<br />
The configuration can be tested with <code>sudo apachectl -t</code> and Apache reloaded with <code>sudo service apache2 reload</code>.<br />
<br />
Extreme care should be taken when using this feature, as an invalid configuration will prevent Apache from starting, as as such is considered a feature for advanced users only.<br />
<br />
==Further Modifying the Apache Configuration==<br />
The majority of typical changes to the Apache configuration can be made via relevant <code>.htaccess</code> files, with most of others available via <code>conf/apache.d/</code>.<br />
<br />
In the event you need to make custom changes to the Apache configuration for an individual site, configuration files can be found in <code>/etc/apache/sites-enabled</code>. Note that if you do make any changes, the configuration will no longer be managed by Sympl and it won't make any changes if the templates are updated. If you want to revert to a Sympl generated configuration for a specific domain, you can do this with <code>sudo sympl-web-configure --verbose '''''example.com'''''</code><br />
<br />
If you want to update the configuration of all sites, then you can edit the templates used to generate the Apache configurations, but you should take care when making any changes to ensure the result is valid. These can be found in <code>/etc/sympl/apache.d</code>, and the existing templated configurations can be regenerated with <code>sudo sympl-web-configure --verbose</code>. Note that any changes to the template files will prevent the templates from being automatically updated, pause updates to the <code>sympl-web</code> package until <br />
<br />
Finally, if you want to create your own Apache configurations not managed by Sympl you can do, as it will not make any changes to them.<br />
<br />
==Configuration Reference==<br />
<section begin="config" /><br />
{| class="wikitable sortable"<br />
|+<br />
!File or Directory<br />
!Used For<br />
!<br />
|-<br />
|<code>.../config/ip</code><br />
|Contains a list of IP addresses which a website will be bound to. Defaults to the primary IPs (IPv4 and IPv6) of your server.<br />
|[[Website Configuration Reference#Serving Content on an Alternate IP Address.|<small>More...</small>]]<br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/ssl-only</code><br />
|Redirects all non-HTTPS traffic for the site to HTTPS.<br />
|[[Website Configuration Reference#Enforcing HTTPS|<small>More...</small>]]<br />
|-<br />
|<code>.../config/hsts</code><br />
|Enables HSTS for HTTPS sites.<br />
|<small>[[Website Configuration Reference#HTTP Strict Transport Security (HSTS)|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/php</code><br />
|Selects the PHP version the site should be run under. Remove the file to default to the bundled version for your distribution.<br />
|<small>[[Website Configuration Reference#Selecting a PHP Version|More...]]</small><br />
|-<br />
|<code>.../config/php-modules</code><br />
|A list of PHP modules/extension package names for the site which will be installed automatically.<br />
|<small>[[Website Configuration Reference#Selecting a PHP Version|More...]]</small><br />
|-<br />
|<code>.../config/php-pool<br />
|Defines the alphanumeric name of the PHP pool for the site.<br />
|<small>[[Website Configuration Reference#Selecting a PHP Version|More...]]</small><br />
|-<br />
|<code>.../config/php-user</code><br />
|The local system user to run PHP as<br />
|<small>[[Website Configuration Reference#Extended Configuration|More...]]</small><br />
|-<br />
|<code>.../config/php-group</code><br />
|The local group to run PHP as.<br />
|<small>[[Website Configuration Reference#Extended Configuration|More...]]</small><br />
|-<br />
|<code>.../config/disable-php-security</code><br />
|Existence of this file will disable some of the PHP security functions in the automatically generated [[Apache]] configurations.<br />
|<small>[[Website Configuration Reference#PHP Security|More...]]</small><br />
|-<br />
|<code>/etc/sympl/php/<version>/includes.d/<pool_name>.conf</code><br />
|Configuration changes for a specific PHP pool should be placed here.<br />
|<small>[[Website Configuration Reference#Extended Configuration|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/disable-filesystem-security</code><br />
|Existence of this file will disable the automatic filesystem security tasks on this domain.<br />
|<small>[[Website Configuration Reference#Filesystem Permissions|More...]]</small><br />
|-<br />
|<code>.../config/public-user</code><br />
|UID or user name of the user to change ownership of the <code>public/</code> directory to. Defaults to www-data.<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
|<code>.../config/public-group</code><br />
|GID or group name of the user to change ownership of the <code>public/</code> directory to. Defaults to www-data.<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/stats</code><br />
|This file enables automatic generation of [[Web Statistics|web stats]] with [[Awffull]]/[[Webalizer]]<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
|<code>.../config/stats-htaccess</code><br />
|A '[[htpasswd]]' format file used to access the [[Web Statistics|web stats]].<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
|<code>.../config/apache.d/'''''example'''''.conf</code><br />
|Apache config files to be included in the site configuration.<br />
|<small>[[Website Configuration Reference#Custom Additions to the Apache Configuration|More...]]</small><br />
|}<section end="config" /><br />
<br />
<blockquote>See also [[Configuration Reference|''Configuration Reference'']] for other configuration files.</blockquote><br />
[[Category:Web]]<br />
[[Category:Reference]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Website_Configuration_Reference&diff=5015Website Configuration Reference2023-06-12T17:22:11Z<p>Kelduum: /* Configuration Reference */</p>
<hr />
<div>This page is a detailed breakdown of all the configuration options and files available when configuring website hosting on Sympl.<br />
<br />
As with all the other documentation here, the site <code>'''''example.com'''''</code> will used, and you should substitute this for your domain.<br />
<br />
All configuration for this domain will be in the /srv/example.com/ directory.<br />
<br />
Sympl uses the [[Apache]] web server, along with the relevant version of [[PHP]] for your version of [[Debian]], along with the typical PHP extensions. See [[Supported PHP Versions]].<br />
<br />
==Getting Started==<br />
The files for example.com are in the <code>/srv/'''''example.com'''''/public/htdocs</code> directory which is the site root.<br />
<br />
*If this directory doesn't exist, is empty, or has no <code>index.php</code> or <code>index.html</code>, the default page will be served, mentioning there is no content on the site.<br />
*The content in the directory will be served for both www.example.com and example.com, so theres no need to prefix the domain with www.<br />
*If you want to serve different content for www.example.com and example.com, you can create /srv/www.example.com as a separate directory.<br />
*Within an hour of the directory creation, a new configuration will [[Sympl-web-configure|automatically be created]] for Apache.<br />
<br />
More detailed information about how Sympl serves content can be found at ''[[How Web Hosting Works on Sympl]]''.<br />
<br />
==Testing Your Sites==<br />
New sites can be tested before they are made live using the 'testing' domains. If your hosting provider provides a wildcard DNS entry on your server pointing to its hostname (and the [[Default Site|default site]] is set to match), then sites can be accessed via this method.<br />
<br />
You can confirm if this is the case using <code>dig</code> or a similar tool - if your server is named <code>'''''server.example.host'''''</code>, if you run <code>dig +short randomname.'''''server.example.host'''''</code> and get a response with the server's IP address, then this is the case.<br />
<br />
If so, you can access any of the sites via this method in the format <domain_directory>.testing.<server_hostname>, for example <code>'''''example.com'''''.testing.'''''server.example.host'''''</code>. Note that the <code>www.</code> should not be included in this case.<br />
<br />
Note that this only applies to websites (not email, FTP and similar), and will not work fully in all instances, as some sites will redirect to their expected hostname or similar. If this is the case, you can test by [[Editing Your Hosts File|editing your hosts file]] on your local computer.<br />
<br />
== PHP Configuration ==<br />
<br />
PHP is the scripting language which the popular Content Management Systems and most websites is written in. It's very popular due to it's flexibility and ease of use, which means that the development of PHP moves quickly, with new versions released every year or so.<br />
<br />
With PHP development moving quickly, the Debian release cycle being every two years, and the common need to run sites on older versions, it's not uncommon to see an instance where you need a different version of PHP than the one bundled with the operating system.<br />
<br />
=== Selecting a PHP Version ===<br />
This isn't currently possible to do automatically on Sympl 11 and earlier, there are community-supported work-arounds. Sympl 12 adds support for selectable PHP versions, and this functionality is being back-ported to earlier versions.<br />
<br />
{{Template:Sympl 12 Only}}<br />
To select a PHP version for a specific site, place the PHP major and minor versions (such as '5.6', '7.3' or '8.1') in the file <code>config/php</code> and run <code>sudo sympl-php-configure</code>.<br />
<br />
This will then install the relevant PHP version from [https://deb.sury.org https://deb.sury.org] if required, along with the typical PHP packages, and configure the site to use that PHP version. Note there is a small extra disk space requirement for each extra version of PHP installed.<br />
<br />
If other PHP modules/extensions are required for the site, their package names can be placed in <code>config/php-modules</code>, and they will be installed automatically the next time <code>sudo sympl-php-configure</code> is run. Package names are the name of the Debian packaged modules without the PHP version, so the <code>php8.1-tidy</code> package would be listed in the file as <code>tidy</code>. PHP extensions can also be installed manually using apt.<br />
<br />
All sites default to a pool named 'default' unless specified otherwise in <code>config/php-pool</code>. If you require any configuration changes, or wish to adjust resources for a site, you should configure it with it's own pool. Note that each pool has its own memory requirements and PHP instances standing by, so running a large number of pools will consume more RAM on your server.<br />
<br />
=== .htaccess vs .user.ini ===<br />
{{Template:Sympl 12 Only}}<br />
When using the default PHP version (ie: not specifying one) the site will run under the default PHP version for the distribution (ie: PHP 8.2 for Debian Bookworm) using 'mod_apache'. This will parse PHP variables and overrides via the <code>.htaccess</code> file in the web content directory, allowing you to make changes on a per-directory basis.<br />
<br />
Running a site under 'FPM' as the configured sites do means they are only passed the relevant file, so require the same configuration entries in a slightly different format in the file <code>.user.ini</code> file, in the same location as <code>.htaccess</code>.<br />
<br />
If you don't already have a <code>.user.ini</code> file in place, Sympl will automatically create and manage one for you each time <code>sudo sympl-php-configure</code> is run. <br />
<br />
=== PHP Command Line ===<br />
{{Template:Sympl 12 Only}}<br />
In some instances, you may need to run the PHP from the command line but need a version other than the default. To do so, rather than using the plain <code>php example.php</code> command, simply append the version, for example <code>php8.1 example.php</code>.<br />
<br />
=== Extended Configuration ===<br />
{{Template:Sympl 12 Only}}<br />
Sympl supports a number of other extended configuration options, including selectable user and group that the PHP pool should be executed as, with <code>config/php-user</code> and <code>config/php-group</code> respectively. These default to www-data, but if must exist if they are changed, and cannot be system users (ie: with an ID below 1000).<br />
<br />
As the PHP pool files are managed automatically by Sympl to ensure that PHP continues running, manual changes to the pool configurations will be overwritten on each run.<br />
<br />
If a change to a pool configuration is required, extra configuration lines can be added to <code>/etc/sympl/php/<version>/includes.d/<pool_name>.conf</code>. The pool name is defined as <code><pool_name>[_<username>[_<groupname>]]</code> with the username and group being optional if not left on the default.<br />
<br />
===PHP Security===<br />
By default, a number of rules are included in the Apache configuration which limit the access of sites running PHP, preventing a compromised site from accessing content outside the <code>/srv/example.com/public/</code> directory, and setting both a domain-specific temp directory and session directory as <code>/srv/example.com/php_tmp/</code> and <code>/srv/example.com/php_sessions/</code> respectively.<br />
<br />
A default configuration is also in place for the ever-popular [[WordPress]], which prevents PHP files from being accessed or executed from within the upload folder, which tend to be the source of most site compromises.<br />
<br />
These restrictions can be disabled by creating the file <code>/srv/example.com/config/disable-php-security</code>, and running <code>sudo sympl-web-configure</code>.<br />
<br />
====PHP Lockdown====<br />
Also available but not enabled by default is a '[[PHP Lockdown|lockdown]]' configuration, which limits a number of potentially dangerous functions in PHP for ''all sites'' where a PHP version is not selected.<br />
<br />
This can be enabled with the command line...<br />
<br />
'''For Sympl 10.x'''<br />
sudo ln -s /etc/php/7.0/mods-available/sympl-web-lockdown.ini /etc/php/7.0/apache2/conf.d/01-sympl-web-lockdown.ini<br />
sudo service apache2 reload<br />
'''For Sympl 11.x'''<br />
sudo ln -s /etc/php/7.3/mods-available/sympl-web-lockdown.ini /etc/php/7.3/apache2/conf.d/01-sympl-web-lockdown.ini<br />
sudo service apache2 reload<br />
'''For Sympl 12.x'''<br />
sudo ln -s /etc/php/8.2/mods-available/sympl-web-lockdown.ini /etc/php/8.2/apache2/conf.d/01-sympl-web-lockdown.ini<br />
sudo service apache2 reload<br />
<br />
Note that this will significantly restrict PHP access, and will affect all sites on the same server, so you should confirm that all sites work as expected once this has been run.<br />
<br />
==Serving the Same Content on Multiple Domains.==<br />
In some cases you may want to accept traffic for and serve the same content for multiple domains, such as [[WordPress Multi-site|WordPress multi-site]] configurations.<br />
<br />
Both of these assume you have the main site already configured and working.<br />
<br />
===Aliasing the Whole Domain===<br />
The most simple option is to alias the whole domain. This will result in the whole configuration including other services such as email, SSL certificates, and FTP sites all sharing the same domain.<br />
<br />
To do this, you only need to create a [[Symbolic Link|symbolic link]] to the directory of the site you want to alias. Aliasing <code>'''''example.org'''''</code> (new domain) to <code>'''''example.com'''''</code> (existing domain) you would use<br />
ln -s /srv/'''''example.com''''' /srv/'''''example.org'''''<br />
<br />
===Aliasing the Web Content Only===<br />
Slightly more complicated, but more flexible is to alias only the <code>public/</code> or <code>public/htdocs/</code> directory. This allows separate email, SSL certificates and individual, which don't reference the main domain. Some sites access content at the directory above <code>htdocs/</code>, in which case you should link at the <code>public/</code> point, otherwise <code>public/htdocs/</code> is usually preferable as it provides separate logging and allows individual FTP access.<br />
<br />
In the examples below, <code>example.com</code> is the site which already exists, and <code>example.org</code> is the new domain.<br />
<br />
====Aliasing public/htdocs/ Only====<br />
mkdir -p /srv/example.org/public<br />
ln -s /srv/example.com/public/htdocs /srv/example.org/public/htdocs<br />
touch /srv/example.org/config/disable-php-security<br />
<br />
====Aliassing public/ and Subdirectories====<br />
mkdir -p /srv/example.org<br />
ln -s /srv/example.com/public /srv/example.org/public<br />
touch /srv/example.org/config/disable-php-security<br />
<br />
====A Note on PHP Security====<br />
By default, PHP processes are restricted to the specific <code>public/</code> directory. This is fine in normal use, but as the links created above are resolved to their targets, they don't match the paths expected and will cause PHP errors. As a workaround, creating the <code>config/disable-php-security</code> file for the new alias disables this restriction, slightly reducing the security of the sites.<br />
<br />
==Serving Content on an Alternate IP Address==<br />
<blockquote>Note that the IP addresses must be valid IPs allocated and routed to your server for this to function.</blockquote>By default, Sympl uses the primary IP addresses (both IPv4 and IPv6) to serve content on. To override this and serve content via another IP address, add the IPs to <code>/srv/'''''example.com'''''/config/ip</code>, followed by <code>sudo sympl-configure-ips</code> to automatically add the IP addresses to the relevant interface, and <code>sudo sympl-configure-ips</code> to adjust the apache configuration to use the new IPs, at which point you should update the DNS for the domain.<br />
<br />
==Enforcing HTTPS==<br />
By default, Sympl will attempt to download a [[Let's Encrypt]] [[SSL Certificate|SSL certificate]] for each site automatically, and will then adjust the Apache configuration to enable it.<br />
<br />
In many cases you will likely want to enforce HTTPS usage on a domain to ensure end-to-end security, and this can be done easily by creating the file <code>/srv/'''''example.com'''''/config/ssl-only</code>.<br />
<br />
This change will take effect automatically within the next hour, but requires a working certificate.<br />
<br />
===HTTP Strict Transport Security (HSTS)===<br />
Once SSL has been enforced, you may also want to ensure users only ever access the site via HTTPS. This can be done by enabling [[HTTP Strict Transport Security|HSTS]], which instructs the users browser to only connect via HTTPS for the next six months.<br />
<br />
You should ensure the site is working properly via HTTPS before enabling this function, but once done, create the file <code>/srv/'''''example.com'''''/config/hsts</code> and the configuration will be updated within the next hour.<br />
<br />
==Redirecting to a Preferred Domain==<br />
In the event you want to force all traffic to the same domain name, this can be done with an [[Apache Rewrites|Apache rewrite]]. This this example, we want to ensure the domain being used is always <code>www.'''''example.com'''''</code>, preventing anyone from using <code>'''''example.com'''''</code> without the <code>www.</code>.<br />
<br />
To do this, you would create a file named <code>.htaccess</code> in the <code>htdocs/</code> directory with this content:<br />
RewriteEngine on<br />
RewriteCond %{HTTP_HOST} !^www.*$ [NC]<br />
RewriteRule ^(.*)$ <nowiki>http://www.%{HTTP_HOST}/$1</nowiki> [R=302,L]<br />
What this set of rules do is:<br />
<br />
#Enable the rewriting of content.<br />
#If the hostname being used does not start with 'www.' (case insensitive)<br />
#Temporarily redirect the request to the same hostname but with 'www.' added and don't process any rules.<br />
<br />
Once this is working as expected, you can change the <code>R=302</code> to <code>R=301</code> to swap the temporary redirect to a permanent one which will be cached by the browser.<blockquote>More information is available at ''[[Apache Rewrites]]''.</blockquote><br />
<br />
<br />
<br />
==Filesystem Permissions==<br />
By default, Sympl adjusts the permissions of files and directories in <code>/srv/'''''example.com'''''/public</code> to ensure web applications can update themselves correctly, and FTP users can make changes as desired.<br />
<br />
This defaults to changing the files and directories to be readable, writable, and owned by the <code>www-data</code> user and the <code>www-data</code> group (which the <code>sympl</code> user is a member of). These defaults can be changed by placing the name or ID of the desired user and group into <code>config/public-user</code> and <code>config/public-group</code>.<br />
<br />
This functionality can be coupled with individual PHP instances for each site (not yet implemented in Sympl) or can be disabled on each domain by creating the file <code>/srv/'''''example.com'''''/config/disable-filesystem-security</code>.<blockquote>See ''[[Filesystem Security]]'' for more information.</blockquote><br />
<br />
==Logging==<br />
By default, the Apache logs are written to <code>/srv/'''''example.com'''''/public/logs</code>, named as either <code>access.log</code> and <code>error.log</code> for HTTP requests, and <code>ssl_access.log</code> and <code>ssl_error.log</code> for HTTPS.<br />
<br />
These are automatically rotated daily, and compressed after two days.<br />
<br />
For any sites being served with [[Mass Hosting|mass hosting]], the logs can be found at <code>/var/log/apache2/zz-mass-hosting.access.log</code> and <code>/var/log/apache2/zz-mass-hosting.error.log</code> .<br />
<br />
Logging for any other traffic is written to <code>/var/log/apache2/other_vhosts_access.log</code>, with any errors for Apache itself at <code>/var/log/apache2/error.log</code>.<br />
<br />
==Web Statistics==<br />
Basic traffic statistics can be optionally generated for the domain from the web logs using [[AWFFull]] (or [[Webalizer]] on Sympl 10 and older), and are written to <code>/srv/'''''example.com'''''/public/htdocs/stats</code>, making them available at <code>https://'''''example.com'''''/stats</code>. <br />
<br />
To trigger the generation, create a file at <code>/srv/'''''example.com'''''/config/stats</code>, and they will be generated automatically overnight for the previous day(s).<br />
<br />
As they contain potentially sensitive information (i.e. client IPs), they are automatically protected by a username and password. To access them you must create a username and password in <code>config/stats-htaccess</code> using <code>htpasswd</code>:<blockquote>'''Note:''' If the file already exists, you should omit the -c parameter or a fresh configuration file will be created and overwrite anything there.</blockquote><br />
htpasswd -c /srv/'''''example.com'''''/config/stats-htaccess '''''username'''''<br />
You will be prompted for a password and confirmation, and you will then be able to log in.<br />
<br />
A template for Webalizer will automatically be written to <code>config/webalizer.conf</code> when the statistics are created, and this can be edited as desired.<br />
<br />
==CGI Scripts==<br />
CGI Scripts are executable code of some kind (binaries or scripts) which are run directly on the operating system, and return the content for a page. Due to them being executable they can be a security risk, so caution should be taken when using them. Usage of CGI Scripts has mostly been supplanted by [[PHP]], however some legacy code <br />
<br />
To use CGI Scripts on your domain, you should copy them to <code>/srv/'''''example.com'''''/public/cgi-bin/</code> and they will then be served at <code>http://'''''example.com'''''/cgi-bin/</code> as long as the files are set executable. Non-executable files will result in an error message rather than serving the content of the file.<br />
<br />
Any files in the <code>public/cgi-bin</code> will not have their permissions updated by <code>sympl-filesystem-security</code>, so it is up to the user to ensure they are set securely, and readable only by the relevant users. Typically they are not be expected to be writable.<br />
<br />
==Custom Additions to the Apache Configuration==<br />
For sites with individual configuration files, custom additions can be made to the Apache configuration by adding files with the <code>.conf</code> extension to <code>/srv/'''''example.com'''''/conf/apache.d/</code>. These will be read when Apache is reloaded or started, and can be used to make changes to the configuration without using <code>.htaccess</code> files.<br />
<br />
The configuration can be tested with <code>sudo apachectl -t</code> and Apache reloaded with <code>sudo service apache2 reload</code>.<br />
<br />
Extreme care should be taken when using this feature, as an invalid configuration will prevent Apache from starting, as as such is considered a feature for advanced users only.<br />
<br />
==Further Modifying the Apache Configuration==<br />
The majority of typical changes to the Apache configuration can be made via relevant <code>.htaccess</code> files, with most of others available via <code>conf/apache.d/</code>.<br />
<br />
In the event you need to make custom changes to the Apache configuration for an individual site, configuration files can be found in <code>/etc/apache/sites-enabled</code>. Note that if you do make any changes, the configuration will no longer be managed by Sympl and it won't make any changes if the templates are updated. If you want to revert to a Sympl generated configuration for a specific domain, you can do this with <code>sudo sympl-web-configure --verbose '''''example.com'''''</code><br />
<br />
If you want to update the configuration of all sites, then you can edit the templates used to generate the Apache configurations, but you should take care when making any changes to ensure the result is valid. These can be found in <code>/etc/sympl/apache.d</code>, and the existing templated configurations can be regenerated with <code>sudo sympl-web-configure --verbose</code>. Note that any changes to the template files will prevent the templates from being automatically updated, pause updates to the <code>sympl-web</code> package until <br />
<br />
Finally, if you want to create your own Apache configurations not managed by Sympl you can do, as it will not make any changes to them.<br />
<br />
==Configuration Reference==<br />
<section begin="config" /><br />
{| class="wikitable sortable"<br />
|+<br />
!File or Directory<br />
!Used For<br />
!<br />
|-<br />
|<code>.../config/ip</code><br />
|Contains a list of IP addresses which a website will be bound to. Defaults to the primary IPs (IPv4 and IPv6) of your server.<br />
|[[Website Configuration Reference#Serving Content on an Alternate IP Address.|<small>More...</small>]]<br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/ssl-only</code><br />
|Redirects all non-HTTPS traffic for the site to HTTPS.<br />
|[[Website Configuration Reference#Enforcing HTTPS|<small>More...</small>]]<br />
|-<br />
|<code>.../config/hsts</code><br />
|Enables HSTS for HTTPS sites.<br />
|<small>[[Website Configuration Reference#HTTP Strict Transport Security (HSTS)|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/php</code><br />
|Selects the PHP version the site should be run under. Remove the file to default to the bundled version for your distribution.<br />
|<small>[[Website Configuration Reference#Selecting a PHP Version|More...]]</small><br />
|-<br />
|<code>.../config/php-modules</code><br />
|A list of PHP modules/extension package names for the site which will be installed automatically.<br />
|<small>[[Website Configuration Reference#Selecting a PHP Version|More...]]</small><br />
|-<br />
|<code>.../config/php-pool<br />
|Defines the alphanumeric name of the PHP pool for the site.<br />
|<small>[[Website Configuration Reference#Selecting a PHP Version|More...]]</small><br />
|-<br />
|<code>.../config/php-user</code><br />
|The local system user to run PHP as<br />
|<small>[[Website Configuration Reference#Extended Configuration|More...]]</small><br />
|-<br />
|<code>.../config/php-group</code><br />
|The local group to run PHP as.<br />
|<small>[[Website Configuration Reference#Extended Configuration|More...]]</small><br />
|-<br />
|<code>.../config/disable-php-security</code><br />
|Existence of this file will disable some of the PHP security functions in the automatically generated [[Apache]] configurations.<br />
|<small>[[Website Configuration Reference#PHP Security|More...]]</small><br />
|-<br />
|<code>/etc/sympl/php/<version>/includes.d/<pool_name>.conf</code><br />
|Configuration changes for a specific PHP pool should be placed here.<br />
|<small>[[Website Configuration Reference#Extended Configuration|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/disable-filesystem-security</code><br />
|Existence of this file will disable the automatic filesystem security tasks on this domain.<br />
|<small>[[Website Configuration Reference#Filesystem Permissions|More...]]</small><br />
|-<br />
|<code>.../config/public-user</code><br />
|UID or user name of the user to change ownership of the <code>public/</code> directory to. Defaults to www-data.<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
|<code>.../config/public-group</code><br />
|GID or group name of the user to change ownership of the <code>public/</code> directory to. Defaults to www-data.<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/stats</code><br />
|This file enables automatic generation of [[Web Statistics|web stats]] with [[Awffull]]/[[Webalizer]]<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
|<code>.../config/stats-htaccess</code><br />
|A '[[htpasswd]]' format file used to access the [[Web Statistics|web stats]].<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
|<code>.../config/apache.d/'''''example'''''.conf</code><br />
|Apache config files to be included in the site configuration.<br />
|<small>[[Website Configuration Reference#Custom Additions to the Apache Configuration|More...]]</small><br />
|}<section end="config" /><br />
<br />
<blockquote>See also [[Configuration Reference|''Configuration Reference'']] for other configuration files.</blockquote><br />
[[Category:Web]]<br />
[[Category:Reference]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Website_Configuration_Reference&diff=5014Website Configuration Reference2023-06-12T17:21:24Z<p>Kelduum: /* PHP Security */</p>
<hr />
<div>This page is a detailed breakdown of all the configuration options and files available when configuring website hosting on Sympl.<br />
<br />
As with all the other documentation here, the site <code>'''''example.com'''''</code> will used, and you should substitute this for your domain.<br />
<br />
All configuration for this domain will be in the /srv/example.com/ directory.<br />
<br />
Sympl uses the [[Apache]] web server, along with the relevant version of [[PHP]] for your version of [[Debian]], along with the typical PHP extensions. See [[Supported PHP Versions]].<br />
<br />
==Getting Started==<br />
The files for example.com are in the <code>/srv/'''''example.com'''''/public/htdocs</code> directory which is the site root.<br />
<br />
*If this directory doesn't exist, is empty, or has no <code>index.php</code> or <code>index.html</code>, the default page will be served, mentioning there is no content on the site.<br />
*The content in the directory will be served for both www.example.com and example.com, so theres no need to prefix the domain with www.<br />
*If you want to serve different content for www.example.com and example.com, you can create /srv/www.example.com as a separate directory.<br />
*Within an hour of the directory creation, a new configuration will [[Sympl-web-configure|automatically be created]] for Apache.<br />
<br />
More detailed information about how Sympl serves content can be found at ''[[How Web Hosting Works on Sympl]]''.<br />
<br />
==Testing Your Sites==<br />
New sites can be tested before they are made live using the 'testing' domains. If your hosting provider provides a wildcard DNS entry on your server pointing to its hostname (and the [[Default Site|default site]] is set to match), then sites can be accessed via this method.<br />
<br />
You can confirm if this is the case using <code>dig</code> or a similar tool - if your server is named <code>'''''server.example.host'''''</code>, if you run <code>dig +short randomname.'''''server.example.host'''''</code> and get a response with the server's IP address, then this is the case.<br />
<br />
If so, you can access any of the sites via this method in the format <domain_directory>.testing.<server_hostname>, for example <code>'''''example.com'''''.testing.'''''server.example.host'''''</code>. Note that the <code>www.</code> should not be included in this case.<br />
<br />
Note that this only applies to websites (not email, FTP and similar), and will not work fully in all instances, as some sites will redirect to their expected hostname or similar. If this is the case, you can test by [[Editing Your Hosts File|editing your hosts file]] on your local computer.<br />
<br />
== PHP Configuration ==<br />
<br />
PHP is the scripting language which the popular Content Management Systems and most websites is written in. It's very popular due to it's flexibility and ease of use, which means that the development of PHP moves quickly, with new versions released every year or so.<br />
<br />
With PHP development moving quickly, the Debian release cycle being every two years, and the common need to run sites on older versions, it's not uncommon to see an instance where you need a different version of PHP than the one bundled with the operating system.<br />
<br />
=== Selecting a PHP Version ===<br />
This isn't currently possible to do automatically on Sympl 11 and earlier, there are community-supported work-arounds. Sympl 12 adds support for selectable PHP versions, and this functionality is being back-ported to earlier versions.<br />
<br />
{{Template:Sympl 12 Only}}<br />
To select a PHP version for a specific site, place the PHP major and minor versions (such as '5.6', '7.3' or '8.1') in the file <code>config/php</code> and run <code>sudo sympl-php-configure</code>.<br />
<br />
This will then install the relevant PHP version from [https://deb.sury.org https://deb.sury.org] if required, along with the typical PHP packages, and configure the site to use that PHP version. Note there is a small extra disk space requirement for each extra version of PHP installed.<br />
<br />
If other PHP modules/extensions are required for the site, their package names can be placed in <code>config/php-modules</code>, and they will be installed automatically the next time <code>sudo sympl-php-configure</code> is run. Package names are the name of the Debian packaged modules without the PHP version, so the <code>php8.1-tidy</code> package would be listed in the file as <code>tidy</code>. PHP extensions can also be installed manually using apt.<br />
<br />
All sites default to a pool named 'default' unless specified otherwise in <code>config/php-pool</code>. If you require any configuration changes, or wish to adjust resources for a site, you should configure it with it's own pool. Note that each pool has its own memory requirements and PHP instances standing by, so running a large number of pools will consume more RAM on your server.<br />
<br />
=== .htaccess vs .user.ini ===<br />
{{Template:Sympl 12 Only}}<br />
When using the default PHP version (ie: not specifying one) the site will run under the default PHP version for the distribution (ie: PHP 8.2 for Debian Bookworm) using 'mod_apache'. This will parse PHP variables and overrides via the <code>.htaccess</code> file in the web content directory, allowing you to make changes on a per-directory basis.<br />
<br />
Running a site under 'FPM' as the configured sites do means they are only passed the relevant file, so require the same configuration entries in a slightly different format in the file <code>.user.ini</code> file, in the same location as <code>.htaccess</code>.<br />
<br />
If you don't already have a <code>.user.ini</code> file in place, Sympl will automatically create and manage one for you each time <code>sudo sympl-php-configure</code> is run. <br />
<br />
=== PHP Command Line ===<br />
{{Template:Sympl 12 Only}}<br />
In some instances, you may need to run the PHP from the command line but need a version other than the default. To do so, rather than using the plain <code>php example.php</code> command, simply append the version, for example <code>php8.1 example.php</code>.<br />
<br />
=== Extended Configuration ===<br />
{{Template:Sympl 12 Only}}<br />
Sympl supports a number of other extended configuration options, including selectable user and group that the PHP pool should be executed as, with <code>config/php-user</code> and <code>config/php-group</code> respectively. These default to www-data, but if must exist if they are changed, and cannot be system users (ie: with an ID below 1000).<br />
<br />
As the PHP pool files are managed automatically by Sympl to ensure that PHP continues running, manual changes to the pool configurations will be overwritten on each run.<br />
<br />
If a change to a pool configuration is required, extra configuration lines can be added to <code>/etc/sympl/php/<version>/includes.d/<pool_name>.conf</code>. The pool name is defined as <code><pool_name>[_<username>[_<groupname>]]</code> with the username and group being optional if not left on the default.<br />
<br />
===PHP Security===<br />
By default, a number of rules are included in the Apache configuration which limit the access of sites running PHP, preventing a compromised site from accessing content outside the <code>/srv/example.com/public/</code> directory, and setting both a domain-specific temp directory and session directory as <code>/srv/example.com/php_tmp/</code> and <code>/srv/example.com/php_sessions/</code> respectively.<br />
<br />
A default configuration is also in place for the ever-popular [[WordPress]], which prevents PHP files from being accessed or executed from within the upload folder, which tend to be the source of most site compromises.<br />
<br />
These restrictions can be disabled by creating the file <code>/srv/example.com/config/disable-php-security</code>, and running <code>sudo sympl-web-configure</code>.<br />
<br />
====PHP Lockdown====<br />
Also available but not enabled by default is a '[[PHP Lockdown|lockdown]]' configuration, which limits a number of potentially dangerous functions in PHP for ''all sites'' where a PHP version is not selected.<br />
<br />
This can be enabled with the command line...<br />
<br />
'''For Sympl 10.x'''<br />
sudo ln -s /etc/php/7.0/mods-available/sympl-web-lockdown.ini /etc/php/7.0/apache2/conf.d/01-sympl-web-lockdown.ini<br />
sudo service apache2 reload<br />
'''For Sympl 11.x'''<br />
sudo ln -s /etc/php/7.3/mods-available/sympl-web-lockdown.ini /etc/php/7.3/apache2/conf.d/01-sympl-web-lockdown.ini<br />
sudo service apache2 reload<br />
'''For Sympl 12.x'''<br />
sudo ln -s /etc/php/8.2/mods-available/sympl-web-lockdown.ini /etc/php/8.2/apache2/conf.d/01-sympl-web-lockdown.ini<br />
sudo service apache2 reload<br />
<br />
Note that this will significantly restrict PHP access, and will affect all sites on the same server, so you should confirm that all sites work as expected once this has been run.<br />
<br />
==Serving the Same Content on Multiple Domains.==<br />
In some cases you may want to accept traffic for and serve the same content for multiple domains, such as [[WordPress Multi-site|WordPress multi-site]] configurations.<br />
<br />
Both of these assume you have the main site already configured and working.<br />
<br />
===Aliasing the Whole Domain===<br />
The most simple option is to alias the whole domain. This will result in the whole configuration including other services such as email, SSL certificates, and FTP sites all sharing the same domain.<br />
<br />
To do this, you only need to create a [[Symbolic Link|symbolic link]] to the directory of the site you want to alias. Aliasing <code>'''''example.org'''''</code> (new domain) to <code>'''''example.com'''''</code> (existing domain) you would use<br />
ln -s /srv/'''''example.com''''' /srv/'''''example.org'''''<br />
<br />
===Aliasing the Web Content Only===<br />
Slightly more complicated, but more flexible is to alias only the <code>public/</code> or <code>public/htdocs/</code> directory. This allows separate email, SSL certificates and individual, which don't reference the main domain. Some sites access content at the directory above <code>htdocs/</code>, in which case you should link at the <code>public/</code> point, otherwise <code>public/htdocs/</code> is usually preferable as it provides separate logging and allows individual FTP access.<br />
<br />
In the examples below, <code>example.com</code> is the site which already exists, and <code>example.org</code> is the new domain.<br />
<br />
====Aliasing public/htdocs/ Only====<br />
mkdir -p /srv/example.org/public<br />
ln -s /srv/example.com/public/htdocs /srv/example.org/public/htdocs<br />
touch /srv/example.org/config/disable-php-security<br />
<br />
====Aliassing public/ and Subdirectories====<br />
mkdir -p /srv/example.org<br />
ln -s /srv/example.com/public /srv/example.org/public<br />
touch /srv/example.org/config/disable-php-security<br />
<br />
====A Note on PHP Security====<br />
By default, PHP processes are restricted to the specific <code>public/</code> directory. This is fine in normal use, but as the links created above are resolved to their targets, they don't match the paths expected and will cause PHP errors. As a workaround, creating the <code>config/disable-php-security</code> file for the new alias disables this restriction, slightly reducing the security of the sites.<br />
<br />
==Serving Content on an Alternate IP Address==<br />
<blockquote>Note that the IP addresses must be valid IPs allocated and routed to your server for this to function.</blockquote>By default, Sympl uses the primary IP addresses (both IPv4 and IPv6) to serve content on. To override this and serve content via another IP address, add the IPs to <code>/srv/'''''example.com'''''/config/ip</code>, followed by <code>sudo sympl-configure-ips</code> to automatically add the IP addresses to the relevant interface, and <code>sudo sympl-configure-ips</code> to adjust the apache configuration to use the new IPs, at which point you should update the DNS for the domain.<br />
<br />
==Enforcing HTTPS==<br />
By default, Sympl will attempt to download a [[Let's Encrypt]] [[SSL Certificate|SSL certificate]] for each site automatically, and will then adjust the Apache configuration to enable it.<br />
<br />
In many cases you will likely want to enforce HTTPS usage on a domain to ensure end-to-end security, and this can be done easily by creating the file <code>/srv/'''''example.com'''''/config/ssl-only</code>.<br />
<br />
This change will take effect automatically within the next hour, but requires a working certificate.<br />
<br />
===HTTP Strict Transport Security (HSTS)===<br />
Once SSL has been enforced, you may also want to ensure users only ever access the site via HTTPS. This can be done by enabling [[HTTP Strict Transport Security|HSTS]], which instructs the users browser to only connect via HTTPS for the next six months.<br />
<br />
You should ensure the site is working properly via HTTPS before enabling this function, but once done, create the file <code>/srv/'''''example.com'''''/config/hsts</code> and the configuration will be updated within the next hour.<br />
<br />
==Redirecting to a Preferred Domain==<br />
In the event you want to force all traffic to the same domain name, this can be done with an [[Apache Rewrites|Apache rewrite]]. This this example, we want to ensure the domain being used is always <code>www.'''''example.com'''''</code>, preventing anyone from using <code>'''''example.com'''''</code> without the <code>www.</code>.<br />
<br />
To do this, you would create a file named <code>.htaccess</code> in the <code>htdocs/</code> directory with this content:<br />
RewriteEngine on<br />
RewriteCond %{HTTP_HOST} !^www.*$ [NC]<br />
RewriteRule ^(.*)$ <nowiki>http://www.%{HTTP_HOST}/$1</nowiki> [R=302,L]<br />
What this set of rules do is:<br />
<br />
#Enable the rewriting of content.<br />
#If the hostname being used does not start with 'www.' (case insensitive)<br />
#Temporarily redirect the request to the same hostname but with 'www.' added and don't process any rules.<br />
<br />
Once this is working as expected, you can change the <code>R=302</code> to <code>R=301</code> to swap the temporary redirect to a permanent one which will be cached by the browser.<blockquote>More information is available at ''[[Apache Rewrites]]''.</blockquote><br />
<br />
<br />
<br />
==Filesystem Permissions==<br />
By default, Sympl adjusts the permissions of files and directories in <code>/srv/'''''example.com'''''/public</code> to ensure web applications can update themselves correctly, and FTP users can make changes as desired.<br />
<br />
This defaults to changing the files and directories to be readable, writable, and owned by the <code>www-data</code> user and the <code>www-data</code> group (which the <code>sympl</code> user is a member of). These defaults can be changed by placing the name or ID of the desired user and group into <code>config/public-user</code> and <code>config/public-group</code>.<br />
<br />
This functionality can be coupled with individual PHP instances for each site (not yet implemented in Sympl) or can be disabled on each domain by creating the file <code>/srv/'''''example.com'''''/config/disable-filesystem-security</code>.<blockquote>See ''[[Filesystem Security]]'' for more information.</blockquote><br />
<br />
==Logging==<br />
By default, the Apache logs are written to <code>/srv/'''''example.com'''''/public/logs</code>, named as either <code>access.log</code> and <code>error.log</code> for HTTP requests, and <code>ssl_access.log</code> and <code>ssl_error.log</code> for HTTPS.<br />
<br />
These are automatically rotated daily, and compressed after two days.<br />
<br />
For any sites being served with [[Mass Hosting|mass hosting]], the logs can be found at <code>/var/log/apache2/zz-mass-hosting.access.log</code> and <code>/var/log/apache2/zz-mass-hosting.error.log</code> .<br />
<br />
Logging for any other traffic is written to <code>/var/log/apache2/other_vhosts_access.log</code>, with any errors for Apache itself at <code>/var/log/apache2/error.log</code>.<br />
<br />
==Web Statistics==<br />
Basic traffic statistics can be optionally generated for the domain from the web logs using [[AWFFull]] (or [[Webalizer]] on Sympl 10 and older), and are written to <code>/srv/'''''example.com'''''/public/htdocs/stats</code>, making them available at <code>https://'''''example.com'''''/stats</code>. <br />
<br />
To trigger the generation, create a file at <code>/srv/'''''example.com'''''/config/stats</code>, and they will be generated automatically overnight for the previous day(s).<br />
<br />
As they contain potentially sensitive information (i.e. client IPs), they are automatically protected by a username and password. To access them you must create a username and password in <code>config/stats-htaccess</code> using <code>htpasswd</code>:<blockquote>'''Note:''' If the file already exists, you should omit the -c parameter or a fresh configuration file will be created and overwrite anything there.</blockquote><br />
htpasswd -c /srv/'''''example.com'''''/config/stats-htaccess '''''username'''''<br />
You will be prompted for a password and confirmation, and you will then be able to log in.<br />
<br />
A template for Webalizer will automatically be written to <code>config/webalizer.conf</code> when the statistics are created, and this can be edited as desired.<br />
<br />
==CGI Scripts==<br />
CGI Scripts are executable code of some kind (binaries or scripts) which are run directly on the operating system, and return the content for a page. Due to them being executable they can be a security risk, so caution should be taken when using them. Usage of CGI Scripts has mostly been supplanted by [[PHP]], however some legacy code <br />
<br />
To use CGI Scripts on your domain, you should copy them to <code>/srv/'''''example.com'''''/public/cgi-bin/</code> and they will then be served at <code>http://'''''example.com'''''/cgi-bin/</code> as long as the files are set executable. Non-executable files will result in an error message rather than serving the content of the file.<br />
<br />
Any files in the <code>public/cgi-bin</code> will not have their permissions updated by <code>sympl-filesystem-security</code>, so it is up to the user to ensure they are set securely, and readable only by the relevant users. Typically they are not be expected to be writable.<br />
<br />
==Custom Additions to the Apache Configuration==<br />
For sites with individual configuration files, custom additions can be made to the Apache configuration by adding files with the <code>.conf</code> extension to <code>/srv/'''''example.com'''''/conf/apache.d/</code>. These will be read when Apache is reloaded or started, and can be used to make changes to the configuration without using <code>.htaccess</code> files.<br />
<br />
The configuration can be tested with <code>sudo apachectl -t</code> and Apache reloaded with <code>sudo service apache2 reload</code>.<br />
<br />
Extreme care should be taken when using this feature, as an invalid configuration will prevent Apache from starting, as as such is considered a feature for advanced users only.<br />
<br />
==Further Modifying the Apache Configuration==<br />
The majority of typical changes to the Apache configuration can be made via relevant <code>.htaccess</code> files, with most of others available via <code>conf/apache.d/</code>.<br />
<br />
In the event you need to make custom changes to the Apache configuration for an individual site, configuration files can be found in <code>/etc/apache/sites-enabled</code>. Note that if you do make any changes, the configuration will no longer be managed by Sympl and it won't make any changes if the templates are updated. If you want to revert to a Sympl generated configuration for a specific domain, you can do this with <code>sudo sympl-web-configure --verbose '''''example.com'''''</code><br />
<br />
If you want to update the configuration of all sites, then you can edit the templates used to generate the Apache configurations, but you should take care when making any changes to ensure the result is valid. These can be found in <code>/etc/sympl/apache.d</code>, and the existing templated configurations can be regenerated with <code>sudo sympl-web-configure --verbose</code>. Note that any changes to the template files will prevent the templates from being automatically updated, pause updates to the <code>sympl-web</code> package until <br />
<br />
Finally, if you want to create your own Apache configurations not managed by Sympl you can do, as it will not make any changes to them.<br />
<br />
==Configuration Reference==<br />
<section begin="config" /><br />
{| class="wikitable sortable"<br />
|+<br />
!File or Directory<br />
!Used For<br />
!<br />
|-<br />
|<code>.../config/ip</code><br />
|Contains a list of IP addresses which a website will be bound to. Defaults to the primary IPs (IPv4 and IPv6) of your server.<br />
|[[Website Configuration Reference#Serving Content on an Alternate IP Address.|<small>More...</small>]]<br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/ssl-only</code><br />
|Redirects all non-HTTPS traffic for the site to HTTPS.<br />
|[[Website Configuration Reference#Enforcing HTTPS|<small>More...</small>]]<br />
|-<br />
|<code>.../config/hsts</code><br />
|Enables HSTS for HTTPS sites.<br />
|<small>[[Website Configuration Reference#HTTP Strict Transport Security (HSTS)|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/php</code><br />
|Selects the PHP version the site should be run under. Remove the file to default to the bundled version for your distribution.<br />
|<small>[[Website Configuration Reference#Selecting a PHP Version|More...]]</small><br />
|-<br />
|<code>.../config/php-modules</code><br />
|A list of PHP modules/extension package names for the site which will be installed automatically.<br />
|<small>[[Website Configuration Reference#Selecting a PHP Version|More...]]</small><br />
|-<br />
|<code>.../config/php-pool<br />
|Defines the alphanumeric name of the PHP pool for the site.<br />
|<small>[[Website Configuration Reference#Selecting a PHP Version|More...]]</small><br />
|-<br />
|<code>.../config/php-user</code><br />
|The local system user to run PHP as<br />
|<small>[[Website Configuration Reference#Extended Configuration|More...]]</small><br />
|-<br />
|<code>.../config/php-group</code><br />
|The local group to run PHP as.<br />
|<small>[[Website Configuration Reference#Extended Configuration|More...]]</small><br />
|-<br />
|<code>.../config/disable-php-security</code><br />
|Existence of this file will disable some of the PHP security functions in the automatically generated [[Apache]] configurations.<br />
|<small>[[Website Configuration Reference#PHP Security|More...]]</small><br />
|-<br />
|<code>/etc/sympl/php/<version>/includes.d/<pool_name>.conf</code><br />
|Configuration changes for a specific PHP pool should be placed here.<br />
|<small>[[Website Configuration Reference#Extended Configuration|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/disable-php-security</code><br />
|Existence of this file will disable some of the PHP security functions in the automatically generated [[Apache]] configurations.<br />
|<small>[[Website Configuration Reference#PHP Security|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/disable-filesystem-security</code><br />
|Existence of this file will disable the automatic filesystem security tasks on this domain.<br />
|<small>[[Website Configuration Reference#Filesystem Permissions|More...]]</small><br />
|-<br />
|<code>.../config/public-user</code><br />
|UID or user name of the user to change ownership of the <code>public/</code> directory to. Defaults to www-data.<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
|<code>.../config/public-group</code><br />
|GID or group name of the user to change ownership of the <code>public/</code> directory to. Defaults to www-data.<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/stats</code><br />
|This file enables automatic generation of [[Web Statistics|web stats]] with [[Awffull]]/[[Webalizer]]<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
|<code>.../config/stats-htaccess</code><br />
|A '[[htpasswd]]' format file used to access the [[Web Statistics|web stats]].<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
|<code>.../config/apache.d/'''''example'''''.conf</code><br />
|Apache config files to be included in the site configuration.<br />
|<small>[[Website Configuration Reference#Custom Additions to the Apache Configuration|More...]]</small><br />
|}<section end="config" /><br />
<br />
<blockquote>See also [[Configuration Reference|''Configuration Reference'']] for other configuration files.</blockquote><br />
[[Category:Web]]<br />
[[Category:Reference]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Website_Configuration_Reference&diff=5013Website Configuration Reference2023-06-12T17:21:00Z<p>Kelduum: /* PHP Configuration */</p>
<hr />
<div>This page is a detailed breakdown of all the configuration options and files available when configuring website hosting on Sympl.<br />
<br />
As with all the other documentation here, the site <code>'''''example.com'''''</code> will used, and you should substitute this for your domain.<br />
<br />
All configuration for this domain will be in the /srv/example.com/ directory.<br />
<br />
Sympl uses the [[Apache]] web server, along with the relevant version of [[PHP]] for your version of [[Debian]], along with the typical PHP extensions. See [[Supported PHP Versions]].<br />
<br />
==Getting Started==<br />
The files for example.com are in the <code>/srv/'''''example.com'''''/public/htdocs</code> directory which is the site root.<br />
<br />
*If this directory doesn't exist, is empty, or has no <code>index.php</code> or <code>index.html</code>, the default page will be served, mentioning there is no content on the site.<br />
*The content in the directory will be served for both www.example.com and example.com, so theres no need to prefix the domain with www.<br />
*If you want to serve different content for www.example.com and example.com, you can create /srv/www.example.com as a separate directory.<br />
*Within an hour of the directory creation, a new configuration will [[Sympl-web-configure|automatically be created]] for Apache.<br />
<br />
More detailed information about how Sympl serves content can be found at ''[[How Web Hosting Works on Sympl]]''.<br />
<br />
==Testing Your Sites==<br />
New sites can be tested before they are made live using the 'testing' domains. If your hosting provider provides a wildcard DNS entry on your server pointing to its hostname (and the [[Default Site|default site]] is set to match), then sites can be accessed via this method.<br />
<br />
You can confirm if this is the case using <code>dig</code> or a similar tool - if your server is named <code>'''''server.example.host'''''</code>, if you run <code>dig +short randomname.'''''server.example.host'''''</code> and get a response with the server's IP address, then this is the case.<br />
<br />
If so, you can access any of the sites via this method in the format <domain_directory>.testing.<server_hostname>, for example <code>'''''example.com'''''.testing.'''''server.example.host'''''</code>. Note that the <code>www.</code> should not be included in this case.<br />
<br />
Note that this only applies to websites (not email, FTP and similar), and will not work fully in all instances, as some sites will redirect to their expected hostname or similar. If this is the case, you can test by [[Editing Your Hosts File|editing your hosts file]] on your local computer.<br />
<br />
== PHP Configuration ==<br />
<br />
PHP is the scripting language which the popular Content Management Systems and most websites is written in. It's very popular due to it's flexibility and ease of use, which means that the development of PHP moves quickly, with new versions released every year or so.<br />
<br />
With PHP development moving quickly, the Debian release cycle being every two years, and the common need to run sites on older versions, it's not uncommon to see an instance where you need a different version of PHP than the one bundled with the operating system.<br />
<br />
=== Selecting a PHP Version ===<br />
This isn't currently possible to do automatically on Sympl 11 and earlier, there are community-supported work-arounds. Sympl 12 adds support for selectable PHP versions, and this functionality is being back-ported to earlier versions.<br />
<br />
{{Template:Sympl 12 Only}}<br />
To select a PHP version for a specific site, place the PHP major and minor versions (such as '5.6', '7.3' or '8.1') in the file <code>config/php</code> and run <code>sudo sympl-php-configure</code>.<br />
<br />
This will then install the relevant PHP version from [https://deb.sury.org https://deb.sury.org] if required, along with the typical PHP packages, and configure the site to use that PHP version. Note there is a small extra disk space requirement for each extra version of PHP installed.<br />
<br />
If other PHP modules/extensions are required for the site, their package names can be placed in <code>config/php-modules</code>, and they will be installed automatically the next time <code>sudo sympl-php-configure</code> is run. Package names are the name of the Debian packaged modules without the PHP version, so the <code>php8.1-tidy</code> package would be listed in the file as <code>tidy</code>. PHP extensions can also be installed manually using apt.<br />
<br />
All sites default to a pool named 'default' unless specified otherwise in <code>config/php-pool</code>. If you require any configuration changes, or wish to adjust resources for a site, you should configure it with it's own pool. Note that each pool has its own memory requirements and PHP instances standing by, so running a large number of pools will consume more RAM on your server.<br />
<br />
=== .htaccess vs .user.ini ===<br />
{{Template:Sympl 12 Only}}<br />
When using the default PHP version (ie: not specifying one) the site will run under the default PHP version for the distribution (ie: PHP 8.2 for Debian Bookworm) using 'mod_apache'. This will parse PHP variables and overrides via the <code>.htaccess</code> file in the web content directory, allowing you to make changes on a per-directory basis.<br />
<br />
Running a site under 'FPM' as the configured sites do means they are only passed the relevant file, so require the same configuration entries in a slightly different format in the file <code>.user.ini</code> file, in the same location as <code>.htaccess</code>.<br />
<br />
If you don't already have a <code>.user.ini</code> file in place, Sympl will automatically create and manage one for you each time <code>sudo sympl-php-configure</code> is run. <br />
<br />
=== PHP Command Line ===<br />
{{Template:Sympl 12 Only}}<br />
In some instances, you may need to run the PHP from the command line but need a version other than the default. To do so, rather than using the plain <code>php example.php</code> command, simply append the version, for example <code>php8.1 example.php</code>.<br />
<br />
=== Extended Configuration ===<br />
{{Template:Sympl 12 Only}}<br />
Sympl supports a number of other extended configuration options, including selectable user and group that the PHP pool should be executed as, with <code>config/php-user</code> and <code>config/php-group</code> respectively. These default to www-data, but if must exist if they are changed, and cannot be system users (ie: with an ID below 1000).<br />
<br />
As the PHP pool files are managed automatically by Sympl to ensure that PHP continues running, manual changes to the pool configurations will be overwritten on each run.<br />
<br />
If a change to a pool configuration is required, extra configuration lines can be added to <code>/etc/sympl/php/<version>/includes.d/<pool_name>.conf</code>. The pool name is defined as <code><pool_name>[_<username>[_<groupname>]]</code> with the username and group being optional if not left on the default.<br />
<br />
==PHP Security==<br />
By default, a number of rules are included in the Apache configuration which limit the access of sites running PHP, preventing a compromised site from accessing content outside the <code>/srv/example.com/public/</code> directory, and setting both a domain-specific temp directory and session directory as <code>/srv/example.com/php_tmp/</code> and <code>/srv/example.com/php_sessions/</code> respectively.<br />
<br />
A default configuration is also in place for the ever-popular [[WordPress]], which prevents PHP files from being accessed or executed from within the upload folder, which tend to be the source of most site compromises.<br />
<br />
These restrictions can be disabled by creating the file <code>/srv/example.com/config/disable-php-security</code>, and running <code>sudo sympl-web-configure</code>.<br />
<br />
===PHP Lockdown===<br />
Also available but not enabled by default is a '[[PHP Lockdown|lockdown]]' configuration, which limits a number of potentially dangerous functions in PHP for ''all sites'' where a PHP version is not selected.<br />
<br />
This can be enabled with the command line...<br />
<br />
'''For Sympl 10.x'''<br />
sudo ln -s /etc/php/7.0/mods-available/sympl-web-lockdown.ini /etc/php/7.0/apache2/conf.d/01-sympl-web-lockdown.ini<br />
sudo service apache2 reload<br />
'''For Sympl 11.x'''<br />
sudo ln -s /etc/php/7.3/mods-available/sympl-web-lockdown.ini /etc/php/7.3/apache2/conf.d/01-sympl-web-lockdown.ini<br />
sudo service apache2 reload<br />
'''For Sympl 12.x'''<br />
sudo ln -s /etc/php/8.2/mods-available/sympl-web-lockdown.ini /etc/php/8.2/apache2/conf.d/01-sympl-web-lockdown.ini<br />
sudo service apache2 reload<br />
<br />
Note that this will significantly restrict PHP access, and will affect all sites on the same server, so you should confirm that all sites work as expected once this has been run.<br />
<br />
==Serving the Same Content on Multiple Domains.==<br />
In some cases you may want to accept traffic for and serve the same content for multiple domains, such as [[WordPress Multi-site|WordPress multi-site]] configurations.<br />
<br />
Both of these assume you have the main site already configured and working.<br />
<br />
===Aliasing the Whole Domain===<br />
The most simple option is to alias the whole domain. This will result in the whole configuration including other services such as email, SSL certificates, and FTP sites all sharing the same domain.<br />
<br />
To do this, you only need to create a [[Symbolic Link|symbolic link]] to the directory of the site you want to alias. Aliasing <code>'''''example.org'''''</code> (new domain) to <code>'''''example.com'''''</code> (existing domain) you would use<br />
ln -s /srv/'''''example.com''''' /srv/'''''example.org'''''<br />
<br />
===Aliasing the Web Content Only===<br />
Slightly more complicated, but more flexible is to alias only the <code>public/</code> or <code>public/htdocs/</code> directory. This allows separate email, SSL certificates and individual, which don't reference the main domain. Some sites access content at the directory above <code>htdocs/</code>, in which case you should link at the <code>public/</code> point, otherwise <code>public/htdocs/</code> is usually preferable as it provides separate logging and allows individual FTP access.<br />
<br />
In the examples below, <code>example.com</code> is the site which already exists, and <code>example.org</code> is the new domain.<br />
<br />
====Aliasing public/htdocs/ Only====<br />
mkdir -p /srv/example.org/public<br />
ln -s /srv/example.com/public/htdocs /srv/example.org/public/htdocs<br />
touch /srv/example.org/config/disable-php-security<br />
<br />
====Aliassing public/ and Subdirectories====<br />
mkdir -p /srv/example.org<br />
ln -s /srv/example.com/public /srv/example.org/public<br />
touch /srv/example.org/config/disable-php-security<br />
<br />
====A Note on PHP Security====<br />
By default, PHP processes are restricted to the specific <code>public/</code> directory. This is fine in normal use, but as the links created above are resolved to their targets, they don't match the paths expected and will cause PHP errors. As a workaround, creating the <code>config/disable-php-security</code> file for the new alias disables this restriction, slightly reducing the security of the sites.<br />
<br />
==Serving Content on an Alternate IP Address==<br />
<blockquote>Note that the IP addresses must be valid IPs allocated and routed to your server for this to function.</blockquote>By default, Sympl uses the primary IP addresses (both IPv4 and IPv6) to serve content on. To override this and serve content via another IP address, add the IPs to <code>/srv/'''''example.com'''''/config/ip</code>, followed by <code>sudo sympl-configure-ips</code> to automatically add the IP addresses to the relevant interface, and <code>sudo sympl-configure-ips</code> to adjust the apache configuration to use the new IPs, at which point you should update the DNS for the domain.<br />
<br />
==Enforcing HTTPS==<br />
By default, Sympl will attempt to download a [[Let's Encrypt]] [[SSL Certificate|SSL certificate]] for each site automatically, and will then adjust the Apache configuration to enable it.<br />
<br />
In many cases you will likely want to enforce HTTPS usage on a domain to ensure end-to-end security, and this can be done easily by creating the file <code>/srv/'''''example.com'''''/config/ssl-only</code>.<br />
<br />
This change will take effect automatically within the next hour, but requires a working certificate.<br />
<br />
===HTTP Strict Transport Security (HSTS)===<br />
Once SSL has been enforced, you may also want to ensure users only ever access the site via HTTPS. This can be done by enabling [[HTTP Strict Transport Security|HSTS]], which instructs the users browser to only connect via HTTPS for the next six months.<br />
<br />
You should ensure the site is working properly via HTTPS before enabling this function, but once done, create the file <code>/srv/'''''example.com'''''/config/hsts</code> and the configuration will be updated within the next hour.<br />
<br />
==Redirecting to a Preferred Domain==<br />
In the event you want to force all traffic to the same domain name, this can be done with an [[Apache Rewrites|Apache rewrite]]. This this example, we want to ensure the domain being used is always <code>www.'''''example.com'''''</code>, preventing anyone from using <code>'''''example.com'''''</code> without the <code>www.</code>.<br />
<br />
To do this, you would create a file named <code>.htaccess</code> in the <code>htdocs/</code> directory with this content:<br />
RewriteEngine on<br />
RewriteCond %{HTTP_HOST} !^www.*$ [NC]<br />
RewriteRule ^(.*)$ <nowiki>http://www.%{HTTP_HOST}/$1</nowiki> [R=302,L]<br />
What this set of rules do is:<br />
<br />
#Enable the rewriting of content.<br />
#If the hostname being used does not start with 'www.' (case insensitive)<br />
#Temporarily redirect the request to the same hostname but with 'www.' added and don't process any rules.<br />
<br />
Once this is working as expected, you can change the <code>R=302</code> to <code>R=301</code> to swap the temporary redirect to a permanent one which will be cached by the browser.<blockquote>More information is available at ''[[Apache Rewrites]]''.</blockquote><br />
<br />
<br />
<br />
==Filesystem Permissions==<br />
By default, Sympl adjusts the permissions of files and directories in <code>/srv/'''''example.com'''''/public</code> to ensure web applications can update themselves correctly, and FTP users can make changes as desired.<br />
<br />
This defaults to changing the files and directories to be readable, writable, and owned by the <code>www-data</code> user and the <code>www-data</code> group (which the <code>sympl</code> user is a member of). These defaults can be changed by placing the name or ID of the desired user and group into <code>config/public-user</code> and <code>config/public-group</code>.<br />
<br />
This functionality can be coupled with individual PHP instances for each site (not yet implemented in Sympl) or can be disabled on each domain by creating the file <code>/srv/'''''example.com'''''/config/disable-filesystem-security</code>.<blockquote>See ''[[Filesystem Security]]'' for more information.</blockquote><br />
<br />
==Logging==<br />
By default, the Apache logs are written to <code>/srv/'''''example.com'''''/public/logs</code>, named as either <code>access.log</code> and <code>error.log</code> for HTTP requests, and <code>ssl_access.log</code> and <code>ssl_error.log</code> for HTTPS.<br />
<br />
These are automatically rotated daily, and compressed after two days.<br />
<br />
For any sites being served with [[Mass Hosting|mass hosting]], the logs can be found at <code>/var/log/apache2/zz-mass-hosting.access.log</code> and <code>/var/log/apache2/zz-mass-hosting.error.log</code> .<br />
<br />
Logging for any other traffic is written to <code>/var/log/apache2/other_vhosts_access.log</code>, with any errors for Apache itself at <code>/var/log/apache2/error.log</code>.<br />
<br />
==Web Statistics==<br />
Basic traffic statistics can be optionally generated for the domain from the web logs using [[AWFFull]] (or [[Webalizer]] on Sympl 10 and older), and are written to <code>/srv/'''''example.com'''''/public/htdocs/stats</code>, making them available at <code>https://'''''example.com'''''/stats</code>. <br />
<br />
To trigger the generation, create a file at <code>/srv/'''''example.com'''''/config/stats</code>, and they will be generated automatically overnight for the previous day(s).<br />
<br />
As they contain potentially sensitive information (i.e. client IPs), they are automatically protected by a username and password. To access them you must create a username and password in <code>config/stats-htaccess</code> using <code>htpasswd</code>:<blockquote>'''Note:''' If the file already exists, you should omit the -c parameter or a fresh configuration file will be created and overwrite anything there.</blockquote><br />
htpasswd -c /srv/'''''example.com'''''/config/stats-htaccess '''''username'''''<br />
You will be prompted for a password and confirmation, and you will then be able to log in.<br />
<br />
A template for Webalizer will automatically be written to <code>config/webalizer.conf</code> when the statistics are created, and this can be edited as desired.<br />
<br />
==CGI Scripts==<br />
CGI Scripts are executable code of some kind (binaries or scripts) which are run directly on the operating system, and return the content for a page. Due to them being executable they can be a security risk, so caution should be taken when using them. Usage of CGI Scripts has mostly been supplanted by [[PHP]], however some legacy code <br />
<br />
To use CGI Scripts on your domain, you should copy them to <code>/srv/'''''example.com'''''/public/cgi-bin/</code> and they will then be served at <code>http://'''''example.com'''''/cgi-bin/</code> as long as the files are set executable. Non-executable files will result in an error message rather than serving the content of the file.<br />
<br />
Any files in the <code>public/cgi-bin</code> will not have their permissions updated by <code>sympl-filesystem-security</code>, so it is up to the user to ensure they are set securely, and readable only by the relevant users. Typically they are not be expected to be writable.<br />
<br />
==Custom Additions to the Apache Configuration==<br />
For sites with individual configuration files, custom additions can be made to the Apache configuration by adding files with the <code>.conf</code> extension to <code>/srv/'''''example.com'''''/conf/apache.d/</code>. These will be read when Apache is reloaded or started, and can be used to make changes to the configuration without using <code>.htaccess</code> files.<br />
<br />
The configuration can be tested with <code>sudo apachectl -t</code> and Apache reloaded with <code>sudo service apache2 reload</code>.<br />
<br />
Extreme care should be taken when using this feature, as an invalid configuration will prevent Apache from starting, as as such is considered a feature for advanced users only.<br />
<br />
==Further Modifying the Apache Configuration==<br />
The majority of typical changes to the Apache configuration can be made via relevant <code>.htaccess</code> files, with most of others available via <code>conf/apache.d/</code>.<br />
<br />
In the event you need to make custom changes to the Apache configuration for an individual site, configuration files can be found in <code>/etc/apache/sites-enabled</code>. Note that if you do make any changes, the configuration will no longer be managed by Sympl and it won't make any changes if the templates are updated. If you want to revert to a Sympl generated configuration for a specific domain, you can do this with <code>sudo sympl-web-configure --verbose '''''example.com'''''</code><br />
<br />
If you want to update the configuration of all sites, then you can edit the templates used to generate the Apache configurations, but you should take care when making any changes to ensure the result is valid. These can be found in <code>/etc/sympl/apache.d</code>, and the existing templated configurations can be regenerated with <code>sudo sympl-web-configure --verbose</code>. Note that any changes to the template files will prevent the templates from being automatically updated, pause updates to the <code>sympl-web</code> package until <br />
<br />
Finally, if you want to create your own Apache configurations not managed by Sympl you can do, as it will not make any changes to them.<br />
<br />
==Configuration Reference==<br />
<section begin="config" /><br />
{| class="wikitable sortable"<br />
|+<br />
!File or Directory<br />
!Used For<br />
!<br />
|-<br />
|<code>.../config/ip</code><br />
|Contains a list of IP addresses which a website will be bound to. Defaults to the primary IPs (IPv4 and IPv6) of your server.<br />
|[[Website Configuration Reference#Serving Content on an Alternate IP Address.|<small>More...</small>]]<br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/ssl-only</code><br />
|Redirects all non-HTTPS traffic for the site to HTTPS.<br />
|[[Website Configuration Reference#Enforcing HTTPS|<small>More...</small>]]<br />
|-<br />
|<code>.../config/hsts</code><br />
|Enables HSTS for HTTPS sites.<br />
|<small>[[Website Configuration Reference#HTTP Strict Transport Security (HSTS)|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/php</code><br />
|Selects the PHP version the site should be run under. Remove the file to default to the bundled version for your distribution.<br />
|<small>[[Website Configuration Reference#Selecting a PHP Version|More...]]</small><br />
|-<br />
|<code>.../config/php-modules</code><br />
|A list of PHP modules/extension package names for the site which will be installed automatically.<br />
|<small>[[Website Configuration Reference#Selecting a PHP Version|More...]]</small><br />
|-<br />
|<code>.../config/php-pool<br />
|Defines the alphanumeric name of the PHP pool for the site.<br />
|<small>[[Website Configuration Reference#Selecting a PHP Version|More...]]</small><br />
|-<br />
|<code>.../config/php-user</code><br />
|The local system user to run PHP as<br />
|<small>[[Website Configuration Reference#Extended Configuration|More...]]</small><br />
|-<br />
|<code>.../config/php-group</code><br />
|The local group to run PHP as.<br />
|<small>[[Website Configuration Reference#Extended Configuration|More...]]</small><br />
|-<br />
|<code>.../config/disable-php-security</code><br />
|Existence of this file will disable some of the PHP security functions in the automatically generated [[Apache]] configurations.<br />
|<small>[[Website Configuration Reference#PHP Security|More...]]</small><br />
|-<br />
|<code>/etc/sympl/php/<version>/includes.d/<pool_name>.conf</code><br />
|Configuration changes for a specific PHP pool should be placed here.<br />
|<small>[[Website Configuration Reference#Extended Configuration|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/disable-php-security</code><br />
|Existence of this file will disable some of the PHP security functions in the automatically generated [[Apache]] configurations.<br />
|<small>[[Website Configuration Reference#PHP Security|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/disable-filesystem-security</code><br />
|Existence of this file will disable the automatic filesystem security tasks on this domain.<br />
|<small>[[Website Configuration Reference#Filesystem Permissions|More...]]</small><br />
|-<br />
|<code>.../config/public-user</code><br />
|UID or user name of the user to change ownership of the <code>public/</code> directory to. Defaults to www-data.<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
|<code>.../config/public-group</code><br />
|GID or group name of the user to change ownership of the <code>public/</code> directory to. Defaults to www-data.<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/stats</code><br />
|This file enables automatic generation of [[Web Statistics|web stats]] with [[Awffull]]/[[Webalizer]]<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
|<code>.../config/stats-htaccess</code><br />
|A '[[htpasswd]]' format file used to access the [[Web Statistics|web stats]].<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
|<code>.../config/apache.d/'''''example'''''.conf</code><br />
|Apache config files to be included in the site configuration.<br />
|<small>[[Website Configuration Reference#Custom Additions to the Apache Configuration|More...]]</small><br />
|}<section end="config" /><br />
<br />
<blockquote>See also [[Configuration Reference|''Configuration Reference'']] for other configuration files.</blockquote><br />
[[Category:Web]]<br />
[[Category:Reference]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Website_Configuration_Reference&diff=5012Website Configuration Reference2023-06-12T17:19:53Z<p>Kelduum: /* Extended Configuration */</p>
<hr />
<div>This page is a detailed breakdown of all the configuration options and files available when configuring website hosting on Sympl.<br />
<br />
As with all the other documentation here, the site <code>'''''example.com'''''</code> will used, and you should substitute this for your domain.<br />
<br />
All configuration for this domain will be in the /srv/example.com/ directory.<br />
<br />
Sympl uses the [[Apache]] web server, along with the relevant version of [[PHP]] for your version of [[Debian]], along with the typical PHP extensions. See [[Supported PHP Versions]].<br />
<br />
==Getting Started==<br />
The files for example.com are in the <code>/srv/'''''example.com'''''/public/htdocs</code> directory which is the site root.<br />
<br />
*If this directory doesn't exist, is empty, or has no <code>index.php</code> or <code>index.html</code>, the default page will be served, mentioning there is no content on the site.<br />
*The content in the directory will be served for both www.example.com and example.com, so theres no need to prefix the domain with www.<br />
*If you want to serve different content for www.example.com and example.com, you can create /srv/www.example.com as a separate directory.<br />
*Within an hour of the directory creation, a new configuration will [[Sympl-web-configure|automatically be created]] for Apache.<br />
<br />
More detailed information about how Sympl serves content can be found at ''[[How Web Hosting Works on Sympl]]''.<br />
<br />
==Testing Your Sites==<br />
New sites can be tested before they are made live using the 'testing' domains. If your hosting provider provides a wildcard DNS entry on your server pointing to its hostname (and the [[Default Site|default site]] is set to match), then sites can be accessed via this method.<br />
<br />
You can confirm if this is the case using <code>dig</code> or a similar tool - if your server is named <code>'''''server.example.host'''''</code>, if you run <code>dig +short randomname.'''''server.example.host'''''</code> and get a response with the server's IP address, then this is the case.<br />
<br />
If so, you can access any of the sites via this method in the format <domain_directory>.testing.<server_hostname>, for example <code>'''''example.com'''''.testing.'''''server.example.host'''''</code>. Note that the <code>www.</code> should not be included in this case.<br />
<br />
Note that this only applies to websites (not email, FTP and similar), and will not work fully in all instances, as some sites will redirect to their expected hostname or similar. If this is the case, you can test by [[Editing Your Hosts File|editing your hosts file]] on your local computer.<br />
<br />
== PHP Configuration ==<br />
<br />
PHP is the scripting language which the popular Content Management Systems and most websites is written in. It's very popular due to it's flexibility and ease of use, which means that the development of PHP moves quickly, with new versions released every year or so.<br />
<br />
With PHP development moving quickly, the Debian release cycle being every two years, and the common need to run sites on older versions, it's not uncommon to see an instance where you need a different version of PHP than the one bundled with the operating system.<br />
<br />
=== Selecting a PHP Version ===<br />
This isn't currently possible to do automatically on Sympl 11 and earlier, there are community-supported work-arounds. Sympl 12 adds support for selectable PHP versions, and this functionality is being back-ported to earlier versions.<br />
<br />
{{Template:Sympl 12 Only}}<br />
To select a PHP version for a specific site, place the PHP major and minor versions (such as '5.6', '7.3' or '8.1') in the file <code>config/php</code> and run <code>sudo sympl-php-configure</code>.<br />
<br />
This will then install the relevant PHP version from [https://deb.sury.org https://deb.sury.org] if required, along with the typical PHP packages, and configure the site to use that PHP version. Note there is a small extra disk space requirement for each extra version of PHP installed.<br />
<br />
If other PHP modules/extensions are required for the site, their package names can be placed in <code>config/php-modules</code>, and they will be installed automatically the next time <code>sudo sympl-php-configure</code> is run. Package names are the name of the Debian packaged modules without the PHP version, so the <code>php8.1-tidy</code> package would be listed in the file as <code>tidy</code>. PHP extensions can also be installed manually using apt.<br />
<br />
All sites default to a pool named 'default' unless specified otherwise in <code>config/php-pool</code>. If you require any configuration changes, or wish to adjust resources for a site, you should configure it with it's own pool. Note that each pool has its own memory requirements and PHP instances standing by, so running a large number of pools will consume more RAM on your server.<br />
<br />
==== .htaccess vs .user.ini ====<br />
{{Template:Sympl 12 Only}}<br />
When using the default PHP version (ie: not specifying one) the site will run under the default PHP version for the distribution (ie: PHP 8.2 for Debian Bookworm) using 'mod_apache'. This will parse PHP variables and overrides via the <code>.htaccess</code> file in the web content directory, allowing you to make changes on a per-directory basis.<br />
<br />
Running a site under 'FPM' as the configured sites do means they are only passed the relevant file, so require the same configuration entries in a slightly different format in the file <code>.user.ini</code> file, in the same location as <code>.htaccess</code>.<br />
<br />
If you don't already have a <code>.user.ini</code> file in place, Sympl will automatically create and manage one for you each time <code>sudo sympl-php-configure</code> is run. <br />
<br />
==== PHP Command Line ====<br />
{{Template:Sympl 12 Only}}<br />
In some instances, you may need to run the PHP from the command line but need a version other than the default. To do so, rather than using the plain <code>php example.php</code> command, simply append the version, for example <code>php8.1 example.php</code>.<br />
<br />
==== Extended Configuration ====<br />
{{Template:Sympl 12 Only}}<br />
Sympl supports a number of other extended configuration options, including selectable user and group that the PHP pool should be executed as, with <code>config/php-user</code> and <code>config/php-group</code> respectively. These default to www-data, but if must exist if they are changed, and cannot be system users (ie: with an ID below 1000).<br />
<br />
As the PHP pool files are managed automatically by Sympl to ensure that PHP continues running, manual changes to the pool configurations will be overwritten on each run.<br />
<br />
If a change to a pool configuration is required, extra configuration lines can be added to <code>/etc/sympl/php/<version>/includes.d/<pool_name>.conf</code>. The pool name is defined as <code><pool_name>[_<username>[_<groupname>]]</code> with the username and group being optional if not left on the default.<br />
<br />
==PHP Security==<br />
By default, a number of rules are included in the Apache configuration which limit the access of sites running PHP, preventing a compromised site from accessing content outside the <code>/srv/example.com/public/</code> directory, and setting both a domain-specific temp directory and session directory as <code>/srv/example.com/php_tmp/</code> and <code>/srv/example.com/php_sessions/</code> respectively.<br />
<br />
A default configuration is also in place for the ever-popular [[WordPress]], which prevents PHP files from being accessed or executed from within the upload folder, which tend to be the source of most site compromises.<br />
<br />
These restrictions can be disabled by creating the file <code>/srv/example.com/config/disable-php-security</code>, and running <code>sudo sympl-web-configure</code>.<br />
<br />
===PHP Lockdown===<br />
Also available but not enabled by default is a '[[PHP Lockdown|lockdown]]' configuration, which limits a number of potentially dangerous functions in PHP for ''all sites'' where a PHP version is not selected.<br />
<br />
This can be enabled with the command line...<br />
<br />
'''For Sympl 10.x'''<br />
sudo ln -s /etc/php/7.0/mods-available/sympl-web-lockdown.ini /etc/php/7.0/apache2/conf.d/01-sympl-web-lockdown.ini<br />
sudo service apache2 reload<br />
'''For Sympl 11.x'''<br />
sudo ln -s /etc/php/7.3/mods-available/sympl-web-lockdown.ini /etc/php/7.3/apache2/conf.d/01-sympl-web-lockdown.ini<br />
sudo service apache2 reload<br />
'''For Sympl 12.x'''<br />
sudo ln -s /etc/php/8.2/mods-available/sympl-web-lockdown.ini /etc/php/8.2/apache2/conf.d/01-sympl-web-lockdown.ini<br />
sudo service apache2 reload<br />
<br />
Note that this will significantly restrict PHP access, and will affect all sites on the same server, so you should confirm that all sites work as expected once this has been run.<br />
<br />
==Serving the Same Content on Multiple Domains.==<br />
In some cases you may want to accept traffic for and serve the same content for multiple domains, such as [[WordPress Multi-site|WordPress multi-site]] configurations.<br />
<br />
Both of these assume you have the main site already configured and working.<br />
<br />
===Aliasing the Whole Domain===<br />
The most simple option is to alias the whole domain. This will result in the whole configuration including other services such as email, SSL certificates, and FTP sites all sharing the same domain.<br />
<br />
To do this, you only need to create a [[Symbolic Link|symbolic link]] to the directory of the site you want to alias. Aliasing <code>'''''example.org'''''</code> (new domain) to <code>'''''example.com'''''</code> (existing domain) you would use<br />
ln -s /srv/'''''example.com''''' /srv/'''''example.org'''''<br />
<br />
===Aliasing the Web Content Only===<br />
Slightly more complicated, but more flexible is to alias only the <code>public/</code> or <code>public/htdocs/</code> directory. This allows separate email, SSL certificates and individual, which don't reference the main domain. Some sites access content at the directory above <code>htdocs/</code>, in which case you should link at the <code>public/</code> point, otherwise <code>public/htdocs/</code> is usually preferable as it provides separate logging and allows individual FTP access.<br />
<br />
In the examples below, <code>example.com</code> is the site which already exists, and <code>example.org</code> is the new domain.<br />
<br />
====Aliasing public/htdocs/ Only====<br />
mkdir -p /srv/example.org/public<br />
ln -s /srv/example.com/public/htdocs /srv/example.org/public/htdocs<br />
touch /srv/example.org/config/disable-php-security<br />
<br />
====Aliassing public/ and Subdirectories====<br />
mkdir -p /srv/example.org<br />
ln -s /srv/example.com/public /srv/example.org/public<br />
touch /srv/example.org/config/disable-php-security<br />
<br />
====A Note on PHP Security====<br />
By default, PHP processes are restricted to the specific <code>public/</code> directory. This is fine in normal use, but as the links created above are resolved to their targets, they don't match the paths expected and will cause PHP errors. As a workaround, creating the <code>config/disable-php-security</code> file for the new alias disables this restriction, slightly reducing the security of the sites.<br />
<br />
==Serving Content on an Alternate IP Address==<br />
<blockquote>Note that the IP addresses must be valid IPs allocated and routed to your server for this to function.</blockquote>By default, Sympl uses the primary IP addresses (both IPv4 and IPv6) to serve content on. To override this and serve content via another IP address, add the IPs to <code>/srv/'''''example.com'''''/config/ip</code>, followed by <code>sudo sympl-configure-ips</code> to automatically add the IP addresses to the relevant interface, and <code>sudo sympl-configure-ips</code> to adjust the apache configuration to use the new IPs, at which point you should update the DNS for the domain.<br />
<br />
==Enforcing HTTPS==<br />
By default, Sympl will attempt to download a [[Let's Encrypt]] [[SSL Certificate|SSL certificate]] for each site automatically, and will then adjust the Apache configuration to enable it.<br />
<br />
In many cases you will likely want to enforce HTTPS usage on a domain to ensure end-to-end security, and this can be done easily by creating the file <code>/srv/'''''example.com'''''/config/ssl-only</code>.<br />
<br />
This change will take effect automatically within the next hour, but requires a working certificate.<br />
<br />
===HTTP Strict Transport Security (HSTS)===<br />
Once SSL has been enforced, you may also want to ensure users only ever access the site via HTTPS. This can be done by enabling [[HTTP Strict Transport Security|HSTS]], which instructs the users browser to only connect via HTTPS for the next six months.<br />
<br />
You should ensure the site is working properly via HTTPS before enabling this function, but once done, create the file <code>/srv/'''''example.com'''''/config/hsts</code> and the configuration will be updated within the next hour.<br />
<br />
==Redirecting to a Preferred Domain==<br />
In the event you want to force all traffic to the same domain name, this can be done with an [[Apache Rewrites|Apache rewrite]]. This this example, we want to ensure the domain being used is always <code>www.'''''example.com'''''</code>, preventing anyone from using <code>'''''example.com'''''</code> without the <code>www.</code>.<br />
<br />
To do this, you would create a file named <code>.htaccess</code> in the <code>htdocs/</code> directory with this content:<br />
RewriteEngine on<br />
RewriteCond %{HTTP_HOST} !^www.*$ [NC]<br />
RewriteRule ^(.*)$ <nowiki>http://www.%{HTTP_HOST}/$1</nowiki> [R=302,L]<br />
What this set of rules do is:<br />
<br />
#Enable the rewriting of content.<br />
#If the hostname being used does not start with 'www.' (case insensitive)<br />
#Temporarily redirect the request to the same hostname but with 'www.' added and don't process any rules.<br />
<br />
Once this is working as expected, you can change the <code>R=302</code> to <code>R=301</code> to swap the temporary redirect to a permanent one which will be cached by the browser.<blockquote>More information is available at ''[[Apache Rewrites]]''.</blockquote><br />
<br />
<br />
<br />
==Filesystem Permissions==<br />
By default, Sympl adjusts the permissions of files and directories in <code>/srv/'''''example.com'''''/public</code> to ensure web applications can update themselves correctly, and FTP users can make changes as desired.<br />
<br />
This defaults to changing the files and directories to be readable, writable, and owned by the <code>www-data</code> user and the <code>www-data</code> group (which the <code>sympl</code> user is a member of). These defaults can be changed by placing the name or ID of the desired user and group into <code>config/public-user</code> and <code>config/public-group</code>.<br />
<br />
This functionality can be coupled with individual PHP instances for each site (not yet implemented in Sympl) or can be disabled on each domain by creating the file <code>/srv/'''''example.com'''''/config/disable-filesystem-security</code>.<blockquote>See ''[[Filesystem Security]]'' for more information.</blockquote><br />
<br />
==Logging==<br />
By default, the Apache logs are written to <code>/srv/'''''example.com'''''/public/logs</code>, named as either <code>access.log</code> and <code>error.log</code> for HTTP requests, and <code>ssl_access.log</code> and <code>ssl_error.log</code> for HTTPS.<br />
<br />
These are automatically rotated daily, and compressed after two days.<br />
<br />
For any sites being served with [[Mass Hosting|mass hosting]], the logs can be found at <code>/var/log/apache2/zz-mass-hosting.access.log</code> and <code>/var/log/apache2/zz-mass-hosting.error.log</code> .<br />
<br />
Logging for any other traffic is written to <code>/var/log/apache2/other_vhosts_access.log</code>, with any errors for Apache itself at <code>/var/log/apache2/error.log</code>.<br />
<br />
==Web Statistics==<br />
Basic traffic statistics can be optionally generated for the domain from the web logs using [[AWFFull]] (or [[Webalizer]] on Sympl 10 and older), and are written to <code>/srv/'''''example.com'''''/public/htdocs/stats</code>, making them available at <code>https://'''''example.com'''''/stats</code>. <br />
<br />
To trigger the generation, create a file at <code>/srv/'''''example.com'''''/config/stats</code>, and they will be generated automatically overnight for the previous day(s).<br />
<br />
As they contain potentially sensitive information (i.e. client IPs), they are automatically protected by a username and password. To access them you must create a username and password in <code>config/stats-htaccess</code> using <code>htpasswd</code>:<blockquote>'''Note:''' If the file already exists, you should omit the -c parameter or a fresh configuration file will be created and overwrite anything there.</blockquote><br />
htpasswd -c /srv/'''''example.com'''''/config/stats-htaccess '''''username'''''<br />
You will be prompted for a password and confirmation, and you will then be able to log in.<br />
<br />
A template for Webalizer will automatically be written to <code>config/webalizer.conf</code> when the statistics are created, and this can be edited as desired.<br />
<br />
==CGI Scripts==<br />
CGI Scripts are executable code of some kind (binaries or scripts) which are run directly on the operating system, and return the content for a page. Due to them being executable they can be a security risk, so caution should be taken when using them. Usage of CGI Scripts has mostly been supplanted by [[PHP]], however some legacy code <br />
<br />
To use CGI Scripts on your domain, you should copy them to <code>/srv/'''''example.com'''''/public/cgi-bin/</code> and they will then be served at <code>http://'''''example.com'''''/cgi-bin/</code> as long as the files are set executable. Non-executable files will result in an error message rather than serving the content of the file.<br />
<br />
Any files in the <code>public/cgi-bin</code> will not have their permissions updated by <code>sympl-filesystem-security</code>, so it is up to the user to ensure they are set securely, and readable only by the relevant users. Typically they are not be expected to be writable.<br />
<br />
==Custom Additions to the Apache Configuration==<br />
For sites with individual configuration files, custom additions can be made to the Apache configuration by adding files with the <code>.conf</code> extension to <code>/srv/'''''example.com'''''/conf/apache.d/</code>. These will be read when Apache is reloaded or started, and can be used to make changes to the configuration without using <code>.htaccess</code> files.<br />
<br />
The configuration can be tested with <code>sudo apachectl -t</code> and Apache reloaded with <code>sudo service apache2 reload</code>.<br />
<br />
Extreme care should be taken when using this feature, as an invalid configuration will prevent Apache from starting, as as such is considered a feature for advanced users only.<br />
<br />
==Further Modifying the Apache Configuration==<br />
The majority of typical changes to the Apache configuration can be made via relevant <code>.htaccess</code> files, with most of others available via <code>conf/apache.d/</code>.<br />
<br />
In the event you need to make custom changes to the Apache configuration for an individual site, configuration files can be found in <code>/etc/apache/sites-enabled</code>. Note that if you do make any changes, the configuration will no longer be managed by Sympl and it won't make any changes if the templates are updated. If you want to revert to a Sympl generated configuration for a specific domain, you can do this with <code>sudo sympl-web-configure --verbose '''''example.com'''''</code><br />
<br />
If you want to update the configuration of all sites, then you can edit the templates used to generate the Apache configurations, but you should take care when making any changes to ensure the result is valid. These can be found in <code>/etc/sympl/apache.d</code>, and the existing templated configurations can be regenerated with <code>sudo sympl-web-configure --verbose</code>. Note that any changes to the template files will prevent the templates from being automatically updated, pause updates to the <code>sympl-web</code> package until <br />
<br />
Finally, if you want to create your own Apache configurations not managed by Sympl you can do, as it will not make any changes to them.<br />
<br />
==Configuration Reference==<br />
<section begin="config" /><br />
{| class="wikitable sortable"<br />
|+<br />
!File or Directory<br />
!Used For<br />
!<br />
|-<br />
|<code>.../config/ip</code><br />
|Contains a list of IP addresses which a website will be bound to. Defaults to the primary IPs (IPv4 and IPv6) of your server.<br />
|[[Website Configuration Reference#Serving Content on an Alternate IP Address.|<small>More...</small>]]<br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/ssl-only</code><br />
|Redirects all non-HTTPS traffic for the site to HTTPS.<br />
|[[Website Configuration Reference#Enforcing HTTPS|<small>More...</small>]]<br />
|-<br />
|<code>.../config/hsts</code><br />
|Enables HSTS for HTTPS sites.<br />
|<small>[[Website Configuration Reference#HTTP Strict Transport Security (HSTS)|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/php</code><br />
|Selects the PHP version the site should be run under. Remove the file to default to the bundled version for your distribution.<br />
|<small>[[Website Configuration Reference#Selecting a PHP Version|More...]]</small><br />
|-<br />
|<code>.../config/php-modules</code><br />
|A list of PHP modules/extension package names for the site which will be installed automatically.<br />
|<small>[[Website Configuration Reference#Selecting a PHP Version|More...]]</small><br />
|-<br />
|<code>.../config/php-pool<br />
|Defines the alphanumeric name of the PHP pool for the site.<br />
|<small>[[Website Configuration Reference#Selecting a PHP Version|More...]]</small><br />
|-<br />
|<code>.../config/php-user</code><br />
|The local system user to run PHP as<br />
|<small>[[Website Configuration Reference#Extended Configuration|More...]]</small><br />
|-<br />
|<code>.../config/php-group</code><br />
|The local group to run PHP as.<br />
|<small>[[Website Configuration Reference#Extended Configuration|More...]]</small><br />
|-<br />
|<code>.../config/disable-php-security</code><br />
|Existence of this file will disable some of the PHP security functions in the automatically generated [[Apache]] configurations.<br />
|<small>[[Website Configuration Reference#PHP Security|More...]]</small><br />
|-<br />
|<code>/etc/sympl/php/<version>/includes.d/<pool_name>.conf</code><br />
|Configuration changes for a specific PHP pool should be placed here.<br />
|<small>[[Website Configuration Reference#Extended Configuration|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/disable-php-security</code><br />
|Existence of this file will disable some of the PHP security functions in the automatically generated [[Apache]] configurations.<br />
|<small>[[Website Configuration Reference#PHP Security|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/disable-filesystem-security</code><br />
|Existence of this file will disable the automatic filesystem security tasks on this domain.<br />
|<small>[[Website Configuration Reference#Filesystem Permissions|More...]]</small><br />
|-<br />
|<code>.../config/public-user</code><br />
|UID or user name of the user to change ownership of the <code>public/</code> directory to. Defaults to www-data.<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
|<code>.../config/public-group</code><br />
|GID or group name of the user to change ownership of the <code>public/</code> directory to. Defaults to www-data.<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/stats</code><br />
|This file enables automatic generation of [[Web Statistics|web stats]] with [[Awffull]]/[[Webalizer]]<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
|<code>.../config/stats-htaccess</code><br />
|A '[[htpasswd]]' format file used to access the [[Web Statistics|web stats]].<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
|<code>.../config/apache.d/'''''example'''''.conf</code><br />
|Apache config files to be included in the site configuration.<br />
|<small>[[Website Configuration Reference#Custom Additions to the Apache Configuration|More...]]</small><br />
|}<section end="config" /><br />
<br />
<blockquote>See also [[Configuration Reference|''Configuration Reference'']] for other configuration files.</blockquote><br />
[[Category:Web]]<br />
[[Category:Reference]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Website_Configuration_Reference&diff=5011Website Configuration Reference2023-06-12T17:19:31Z<p>Kelduum: /* Selecting a PHP Version */</p>
<hr />
<div>This page is a detailed breakdown of all the configuration options and files available when configuring website hosting on Sympl.<br />
<br />
As with all the other documentation here, the site <code>'''''example.com'''''</code> will used, and you should substitute this for your domain.<br />
<br />
All configuration for this domain will be in the /srv/example.com/ directory.<br />
<br />
Sympl uses the [[Apache]] web server, along with the relevant version of [[PHP]] for your version of [[Debian]], along with the typical PHP extensions. See [[Supported PHP Versions]].<br />
<br />
==Getting Started==<br />
The files for example.com are in the <code>/srv/'''''example.com'''''/public/htdocs</code> directory which is the site root.<br />
<br />
*If this directory doesn't exist, is empty, or has no <code>index.php</code> or <code>index.html</code>, the default page will be served, mentioning there is no content on the site.<br />
*The content in the directory will be served for both www.example.com and example.com, so theres no need to prefix the domain with www.<br />
*If you want to serve different content for www.example.com and example.com, you can create /srv/www.example.com as a separate directory.<br />
*Within an hour of the directory creation, a new configuration will [[Sympl-web-configure|automatically be created]] for Apache.<br />
<br />
More detailed information about how Sympl serves content can be found at ''[[How Web Hosting Works on Sympl]]''.<br />
<br />
==Testing Your Sites==<br />
New sites can be tested before they are made live using the 'testing' domains. If your hosting provider provides a wildcard DNS entry on your server pointing to its hostname (and the [[Default Site|default site]] is set to match), then sites can be accessed via this method.<br />
<br />
You can confirm if this is the case using <code>dig</code> or a similar tool - if your server is named <code>'''''server.example.host'''''</code>, if you run <code>dig +short randomname.'''''server.example.host'''''</code> and get a response with the server's IP address, then this is the case.<br />
<br />
If so, you can access any of the sites via this method in the format <domain_directory>.testing.<server_hostname>, for example <code>'''''example.com'''''.testing.'''''server.example.host'''''</code>. Note that the <code>www.</code> should not be included in this case.<br />
<br />
Note that this only applies to websites (not email, FTP and similar), and will not work fully in all instances, as some sites will redirect to their expected hostname or similar. If this is the case, you can test by [[Editing Your Hosts File|editing your hosts file]] on your local computer.<br />
<br />
== PHP Configuration ==<br />
<br />
PHP is the scripting language which the popular Content Management Systems and most websites is written in. It's very popular due to it's flexibility and ease of use, which means that the development of PHP moves quickly, with new versions released every year or so.<br />
<br />
With PHP development moving quickly, the Debian release cycle being every two years, and the common need to run sites on older versions, it's not uncommon to see an instance where you need a different version of PHP than the one bundled with the operating system.<br />
<br />
=== Selecting a PHP Version ===<br />
This isn't currently possible to do automatically on Sympl 11 and earlier, there are community-supported work-arounds. Sympl 12 adds support for selectable PHP versions, and this functionality is being back-ported to earlier versions.<br />
<br />
{{Template:Sympl 12 Only}}<br />
To select a PHP version for a specific site, place the PHP major and minor versions (such as '5.6', '7.3' or '8.1') in the file <code>config/php</code> and run <code>sudo sympl-php-configure</code>.<br />
<br />
This will then install the relevant PHP version from [https://deb.sury.org https://deb.sury.org] if required, along with the typical PHP packages, and configure the site to use that PHP version. Note there is a small extra disk space requirement for each extra version of PHP installed.<br />
<br />
If other PHP modules/extensions are required for the site, their package names can be placed in <code>config/php-modules</code>, and they will be installed automatically the next time <code>sudo sympl-php-configure</code> is run. Package names are the name of the Debian packaged modules without the PHP version, so the <code>php8.1-tidy</code> package would be listed in the file as <code>tidy</code>. PHP extensions can also be installed manually using apt.<br />
<br />
All sites default to a pool named 'default' unless specified otherwise in <code>config/php-pool</code>. If you require any configuration changes, or wish to adjust resources for a site, you should configure it with it's own pool. Note that each pool has its own memory requirements and PHP instances standing by, so running a large number of pools will consume more RAM on your server.<br />
<br />
==== .htaccess vs .user.ini ====<br />
{{Template:Sympl 12 Only}}<br />
When using the default PHP version (ie: not specifying one) the site will run under the default PHP version for the distribution (ie: PHP 8.2 for Debian Bookworm) using 'mod_apache'. This will parse PHP variables and overrides via the <code>.htaccess</code> file in the web content directory, allowing you to make changes on a per-directory basis.<br />
<br />
Running a site under 'FPM' as the configured sites do means they are only passed the relevant file, so require the same configuration entries in a slightly different format in the file <code>.user.ini</code> file, in the same location as <code>.htaccess</code>.<br />
<br />
If you don't already have a <code>.user.ini</code> file in place, Sympl will automatically create and manage one for you each time <code>sudo sympl-php-configure</code> is run. <br />
<br />
==== PHP Command Line ====<br />
{{Template:Sympl 12 Only}}<br />
In some instances, you may need to run the PHP from the command line but need a version other than the default. To do so, rather than using the plain <code>php example.php</code> command, simply append the version, for example <code>php8.1 example.php</code>.<br />
<br />
==== Extended Configuration ====<br />
{{Template:Sympl 12 Only}}<br />
Sympl supports a number of other extended configuration options, including selectable user and group that the PHP pool should be executed as, with <code>config/php-user</code> and <code>config/php-group</code> respectively. These default to www-data, but if must exist if they are changed, and cannot be system users (ie: with an ID below 1000).<br />
<br />
As the PHP pool files are managed automatically by Sympl to ensure that PHP continues running, manual changes to the pool configurations will be overwritten on each run.<br />
<br />
If a change to a pool configuration is required, extra configuration lines can be added to <code>/etc/sympl/php/<version>/includes.d/<pool_name>.conf</code>. The pool name is defined as <code>><pool_name>[_<username>[_<groupname>]]</code>> with the username and group being optional if not left on the default.<br />
<br />
==PHP Security==<br />
By default, a number of rules are included in the Apache configuration which limit the access of sites running PHP, preventing a compromised site from accessing content outside the <code>/srv/example.com/public/</code> directory, and setting both a domain-specific temp directory and session directory as <code>/srv/example.com/php_tmp/</code> and <code>/srv/example.com/php_sessions/</code> respectively.<br />
<br />
A default configuration is also in place for the ever-popular [[WordPress]], which prevents PHP files from being accessed or executed from within the upload folder, which tend to be the source of most site compromises.<br />
<br />
These restrictions can be disabled by creating the file <code>/srv/example.com/config/disable-php-security</code>, and running <code>sudo sympl-web-configure</code>.<br />
<br />
===PHP Lockdown===<br />
Also available but not enabled by default is a '[[PHP Lockdown|lockdown]]' configuration, which limits a number of potentially dangerous functions in PHP for ''all sites'' where a PHP version is not selected.<br />
<br />
This can be enabled with the command line...<br />
<br />
'''For Sympl 10.x'''<br />
sudo ln -s /etc/php/7.0/mods-available/sympl-web-lockdown.ini /etc/php/7.0/apache2/conf.d/01-sympl-web-lockdown.ini<br />
sudo service apache2 reload<br />
'''For Sympl 11.x'''<br />
sudo ln -s /etc/php/7.3/mods-available/sympl-web-lockdown.ini /etc/php/7.3/apache2/conf.d/01-sympl-web-lockdown.ini<br />
sudo service apache2 reload<br />
'''For Sympl 12.x'''<br />
sudo ln -s /etc/php/8.2/mods-available/sympl-web-lockdown.ini /etc/php/8.2/apache2/conf.d/01-sympl-web-lockdown.ini<br />
sudo service apache2 reload<br />
<br />
Note that this will significantly restrict PHP access, and will affect all sites on the same server, so you should confirm that all sites work as expected once this has been run.<br />
<br />
==Serving the Same Content on Multiple Domains.==<br />
In some cases you may want to accept traffic for and serve the same content for multiple domains, such as [[WordPress Multi-site|WordPress multi-site]] configurations.<br />
<br />
Both of these assume you have the main site already configured and working.<br />
<br />
===Aliasing the Whole Domain===<br />
The most simple option is to alias the whole domain. This will result in the whole configuration including other services such as email, SSL certificates, and FTP sites all sharing the same domain.<br />
<br />
To do this, you only need to create a [[Symbolic Link|symbolic link]] to the directory of the site you want to alias. Aliasing <code>'''''example.org'''''</code> (new domain) to <code>'''''example.com'''''</code> (existing domain) you would use<br />
ln -s /srv/'''''example.com''''' /srv/'''''example.org'''''<br />
<br />
===Aliasing the Web Content Only===<br />
Slightly more complicated, but more flexible is to alias only the <code>public/</code> or <code>public/htdocs/</code> directory. This allows separate email, SSL certificates and individual, which don't reference the main domain. Some sites access content at the directory above <code>htdocs/</code>, in which case you should link at the <code>public/</code> point, otherwise <code>public/htdocs/</code> is usually preferable as it provides separate logging and allows individual FTP access.<br />
<br />
In the examples below, <code>example.com</code> is the site which already exists, and <code>example.org</code> is the new domain.<br />
<br />
====Aliasing public/htdocs/ Only====<br />
mkdir -p /srv/example.org/public<br />
ln -s /srv/example.com/public/htdocs /srv/example.org/public/htdocs<br />
touch /srv/example.org/config/disable-php-security<br />
<br />
====Aliassing public/ and Subdirectories====<br />
mkdir -p /srv/example.org<br />
ln -s /srv/example.com/public /srv/example.org/public<br />
touch /srv/example.org/config/disable-php-security<br />
<br />
====A Note on PHP Security====<br />
By default, PHP processes are restricted to the specific <code>public/</code> directory. This is fine in normal use, but as the links created above are resolved to their targets, they don't match the paths expected and will cause PHP errors. As a workaround, creating the <code>config/disable-php-security</code> file for the new alias disables this restriction, slightly reducing the security of the sites.<br />
<br />
==Serving Content on an Alternate IP Address==<br />
<blockquote>Note that the IP addresses must be valid IPs allocated and routed to your server for this to function.</blockquote>By default, Sympl uses the primary IP addresses (both IPv4 and IPv6) to serve content on. To override this and serve content via another IP address, add the IPs to <code>/srv/'''''example.com'''''/config/ip</code>, followed by <code>sudo sympl-configure-ips</code> to automatically add the IP addresses to the relevant interface, and <code>sudo sympl-configure-ips</code> to adjust the apache configuration to use the new IPs, at which point you should update the DNS for the domain.<br />
<br />
==Enforcing HTTPS==<br />
By default, Sympl will attempt to download a [[Let's Encrypt]] [[SSL Certificate|SSL certificate]] for each site automatically, and will then adjust the Apache configuration to enable it.<br />
<br />
In many cases you will likely want to enforce HTTPS usage on a domain to ensure end-to-end security, and this can be done easily by creating the file <code>/srv/'''''example.com'''''/config/ssl-only</code>.<br />
<br />
This change will take effect automatically within the next hour, but requires a working certificate.<br />
<br />
===HTTP Strict Transport Security (HSTS)===<br />
Once SSL has been enforced, you may also want to ensure users only ever access the site via HTTPS. This can be done by enabling [[HTTP Strict Transport Security|HSTS]], which instructs the users browser to only connect via HTTPS for the next six months.<br />
<br />
You should ensure the site is working properly via HTTPS before enabling this function, but once done, create the file <code>/srv/'''''example.com'''''/config/hsts</code> and the configuration will be updated within the next hour.<br />
<br />
==Redirecting to a Preferred Domain==<br />
In the event you want to force all traffic to the same domain name, this can be done with an [[Apache Rewrites|Apache rewrite]]. This this example, we want to ensure the domain being used is always <code>www.'''''example.com'''''</code>, preventing anyone from using <code>'''''example.com'''''</code> without the <code>www.</code>.<br />
<br />
To do this, you would create a file named <code>.htaccess</code> in the <code>htdocs/</code> directory with this content:<br />
RewriteEngine on<br />
RewriteCond %{HTTP_HOST} !^www.*$ [NC]<br />
RewriteRule ^(.*)$ <nowiki>http://www.%{HTTP_HOST}/$1</nowiki> [R=302,L]<br />
What this set of rules do is:<br />
<br />
#Enable the rewriting of content.<br />
#If the hostname being used does not start with 'www.' (case insensitive)<br />
#Temporarily redirect the request to the same hostname but with 'www.' added and don't process any rules.<br />
<br />
Once this is working as expected, you can change the <code>R=302</code> to <code>R=301</code> to swap the temporary redirect to a permanent one which will be cached by the browser.<blockquote>More information is available at ''[[Apache Rewrites]]''.</blockquote><br />
<br />
<br />
<br />
==Filesystem Permissions==<br />
By default, Sympl adjusts the permissions of files and directories in <code>/srv/'''''example.com'''''/public</code> to ensure web applications can update themselves correctly, and FTP users can make changes as desired.<br />
<br />
This defaults to changing the files and directories to be readable, writable, and owned by the <code>www-data</code> user and the <code>www-data</code> group (which the <code>sympl</code> user is a member of). These defaults can be changed by placing the name or ID of the desired user and group into <code>config/public-user</code> and <code>config/public-group</code>.<br />
<br />
This functionality can be coupled with individual PHP instances for each site (not yet implemented in Sympl) or can be disabled on each domain by creating the file <code>/srv/'''''example.com'''''/config/disable-filesystem-security</code>.<blockquote>See ''[[Filesystem Security]]'' for more information.</blockquote><br />
<br />
==Logging==<br />
By default, the Apache logs are written to <code>/srv/'''''example.com'''''/public/logs</code>, named as either <code>access.log</code> and <code>error.log</code> for HTTP requests, and <code>ssl_access.log</code> and <code>ssl_error.log</code> for HTTPS.<br />
<br />
These are automatically rotated daily, and compressed after two days.<br />
<br />
For any sites being served with [[Mass Hosting|mass hosting]], the logs can be found at <code>/var/log/apache2/zz-mass-hosting.access.log</code> and <code>/var/log/apache2/zz-mass-hosting.error.log</code> .<br />
<br />
Logging for any other traffic is written to <code>/var/log/apache2/other_vhosts_access.log</code>, with any errors for Apache itself at <code>/var/log/apache2/error.log</code>.<br />
<br />
==Web Statistics==<br />
Basic traffic statistics can be optionally generated for the domain from the web logs using [[AWFFull]] (or [[Webalizer]] on Sympl 10 and older), and are written to <code>/srv/'''''example.com'''''/public/htdocs/stats</code>, making them available at <code>https://'''''example.com'''''/stats</code>. <br />
<br />
To trigger the generation, create a file at <code>/srv/'''''example.com'''''/config/stats</code>, and they will be generated automatically overnight for the previous day(s).<br />
<br />
As they contain potentially sensitive information (i.e. client IPs), they are automatically protected by a username and password. To access them you must create a username and password in <code>config/stats-htaccess</code> using <code>htpasswd</code>:<blockquote>'''Note:''' If the file already exists, you should omit the -c parameter or a fresh configuration file will be created and overwrite anything there.</blockquote><br />
htpasswd -c /srv/'''''example.com'''''/config/stats-htaccess '''''username'''''<br />
You will be prompted for a password and confirmation, and you will then be able to log in.<br />
<br />
A template for Webalizer will automatically be written to <code>config/webalizer.conf</code> when the statistics are created, and this can be edited as desired.<br />
<br />
==CGI Scripts==<br />
CGI Scripts are executable code of some kind (binaries or scripts) which are run directly on the operating system, and return the content for a page. Due to them being executable they can be a security risk, so caution should be taken when using them. Usage of CGI Scripts has mostly been supplanted by [[PHP]], however some legacy code <br />
<br />
To use CGI Scripts on your domain, you should copy them to <code>/srv/'''''example.com'''''/public/cgi-bin/</code> and they will then be served at <code>http://'''''example.com'''''/cgi-bin/</code> as long as the files are set executable. Non-executable files will result in an error message rather than serving the content of the file.<br />
<br />
Any files in the <code>public/cgi-bin</code> will not have their permissions updated by <code>sympl-filesystem-security</code>, so it is up to the user to ensure they are set securely, and readable only by the relevant users. Typically they are not be expected to be writable.<br />
<br />
==Custom Additions to the Apache Configuration==<br />
For sites with individual configuration files, custom additions can be made to the Apache configuration by adding files with the <code>.conf</code> extension to <code>/srv/'''''example.com'''''/conf/apache.d/</code>. These will be read when Apache is reloaded or started, and can be used to make changes to the configuration without using <code>.htaccess</code> files.<br />
<br />
The configuration can be tested with <code>sudo apachectl -t</code> and Apache reloaded with <code>sudo service apache2 reload</code>.<br />
<br />
Extreme care should be taken when using this feature, as an invalid configuration will prevent Apache from starting, as as such is considered a feature for advanced users only.<br />
<br />
==Further Modifying the Apache Configuration==<br />
The majority of typical changes to the Apache configuration can be made via relevant <code>.htaccess</code> files, with most of others available via <code>conf/apache.d/</code>.<br />
<br />
In the event you need to make custom changes to the Apache configuration for an individual site, configuration files can be found in <code>/etc/apache/sites-enabled</code>. Note that if you do make any changes, the configuration will no longer be managed by Sympl and it won't make any changes if the templates are updated. If you want to revert to a Sympl generated configuration for a specific domain, you can do this with <code>sudo sympl-web-configure --verbose '''''example.com'''''</code><br />
<br />
If you want to update the configuration of all sites, then you can edit the templates used to generate the Apache configurations, but you should take care when making any changes to ensure the result is valid. These can be found in <code>/etc/sympl/apache.d</code>, and the existing templated configurations can be regenerated with <code>sudo sympl-web-configure --verbose</code>. Note that any changes to the template files will prevent the templates from being automatically updated, pause updates to the <code>sympl-web</code> package until <br />
<br />
Finally, if you want to create your own Apache configurations not managed by Sympl you can do, as it will not make any changes to them.<br />
<br />
==Configuration Reference==<br />
<section begin="config" /><br />
{| class="wikitable sortable"<br />
|+<br />
!File or Directory<br />
!Used For<br />
!<br />
|-<br />
|<code>.../config/ip</code><br />
|Contains a list of IP addresses which a website will be bound to. Defaults to the primary IPs (IPv4 and IPv6) of your server.<br />
|[[Website Configuration Reference#Serving Content on an Alternate IP Address.|<small>More...</small>]]<br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/ssl-only</code><br />
|Redirects all non-HTTPS traffic for the site to HTTPS.<br />
|[[Website Configuration Reference#Enforcing HTTPS|<small>More...</small>]]<br />
|-<br />
|<code>.../config/hsts</code><br />
|Enables HSTS for HTTPS sites.<br />
|<small>[[Website Configuration Reference#HTTP Strict Transport Security (HSTS)|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/php</code><br />
|Selects the PHP version the site should be run under. Remove the file to default to the bundled version for your distribution.<br />
|<small>[[Website Configuration Reference#Selecting a PHP Version|More...]]</small><br />
|-<br />
|<code>.../config/php-modules</code><br />
|A list of PHP modules/extension package names for the site which will be installed automatically.<br />
|<small>[[Website Configuration Reference#Selecting a PHP Version|More...]]</small><br />
|-<br />
|<code>.../config/php-pool<br />
|Defines the alphanumeric name of the PHP pool for the site.<br />
|<small>[[Website Configuration Reference#Selecting a PHP Version|More...]]</small><br />
|-<br />
|<code>.../config/php-user</code><br />
|The local system user to run PHP as<br />
|<small>[[Website Configuration Reference#Extended Configuration|More...]]</small><br />
|-<br />
|<code>.../config/php-group</code><br />
|The local group to run PHP as.<br />
|<small>[[Website Configuration Reference#Extended Configuration|More...]]</small><br />
|-<br />
|<code>.../config/disable-php-security</code><br />
|Existence of this file will disable some of the PHP security functions in the automatically generated [[Apache]] configurations.<br />
|<small>[[Website Configuration Reference#PHP Security|More...]]</small><br />
|-<br />
|<code>/etc/sympl/php/<version>/includes.d/<pool_name>.conf</code><br />
|Configuration changes for a specific PHP pool should be placed here.<br />
|<small>[[Website Configuration Reference#Extended Configuration|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/disable-php-security</code><br />
|Existence of this file will disable some of the PHP security functions in the automatically generated [[Apache]] configurations.<br />
|<small>[[Website Configuration Reference#PHP Security|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/disable-filesystem-security</code><br />
|Existence of this file will disable the automatic filesystem security tasks on this domain.<br />
|<small>[[Website Configuration Reference#Filesystem Permissions|More...]]</small><br />
|-<br />
|<code>.../config/public-user</code><br />
|UID or user name of the user to change ownership of the <code>public/</code> directory to. Defaults to www-data.<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
|<code>.../config/public-group</code><br />
|GID or group name of the user to change ownership of the <code>public/</code> directory to. Defaults to www-data.<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/stats</code><br />
|This file enables automatic generation of [[Web Statistics|web stats]] with [[Awffull]]/[[Webalizer]]<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
|<code>.../config/stats-htaccess</code><br />
|A '[[htpasswd]]' format file used to access the [[Web Statistics|web stats]].<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
|<code>.../config/apache.d/'''''example'''''.conf</code><br />
|Apache config files to be included in the site configuration.<br />
|<small>[[Website Configuration Reference#Custom Additions to the Apache Configuration|More...]]</small><br />
|}<section end="config" /><br />
<br />
<blockquote>See also [[Configuration Reference|''Configuration Reference'']] for other configuration files.</blockquote><br />
[[Category:Web]]<br />
[[Category:Reference]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Website_Configuration_Reference&diff=5010Website Configuration Reference2023-06-12T17:17:24Z<p>Kelduum: /* Selecting a PHP Version */</p>
<hr />
<div>This page is a detailed breakdown of all the configuration options and files available when configuring website hosting on Sympl.<br />
<br />
As with all the other documentation here, the site <code>'''''example.com'''''</code> will used, and you should substitute this for your domain.<br />
<br />
All configuration for this domain will be in the /srv/example.com/ directory.<br />
<br />
Sympl uses the [[Apache]] web server, along with the relevant version of [[PHP]] for your version of [[Debian]], along with the typical PHP extensions. See [[Supported PHP Versions]].<br />
<br />
==Getting Started==<br />
The files for example.com are in the <code>/srv/'''''example.com'''''/public/htdocs</code> directory which is the site root.<br />
<br />
*If this directory doesn't exist, is empty, or has no <code>index.php</code> or <code>index.html</code>, the default page will be served, mentioning there is no content on the site.<br />
*The content in the directory will be served for both www.example.com and example.com, so theres no need to prefix the domain with www.<br />
*If you want to serve different content for www.example.com and example.com, you can create /srv/www.example.com as a separate directory.<br />
*Within an hour of the directory creation, a new configuration will [[Sympl-web-configure|automatically be created]] for Apache.<br />
<br />
More detailed information about how Sympl serves content can be found at ''[[How Web Hosting Works on Sympl]]''.<br />
<br />
==Testing Your Sites==<br />
New sites can be tested before they are made live using the 'testing' domains. If your hosting provider provides a wildcard DNS entry on your server pointing to its hostname (and the [[Default Site|default site]] is set to match), then sites can be accessed via this method.<br />
<br />
You can confirm if this is the case using <code>dig</code> or a similar tool - if your server is named <code>'''''server.example.host'''''</code>, if you run <code>dig +short randomname.'''''server.example.host'''''</code> and get a response with the server's IP address, then this is the case.<br />
<br />
If so, you can access any of the sites via this method in the format <domain_directory>.testing.<server_hostname>, for example <code>'''''example.com'''''.testing.'''''server.example.host'''''</code>. Note that the <code>www.</code> should not be included in this case.<br />
<br />
Note that this only applies to websites (not email, FTP and similar), and will not work fully in all instances, as some sites will redirect to their expected hostname or similar. If this is the case, you can test by [[Editing Your Hosts File|editing your hosts file]] on your local computer.<br />
<br />
== PHP Configuration ==<br />
<br />
PHP is the scripting language which the popular Content Management Systems and most websites is written in. It's very popular due to it's flexibility and ease of use, which means that the development of PHP moves quickly, with new versions released every year or so.<br />
<br />
With PHP development moving quickly, the Debian release cycle being every two years, and the common need to run sites on older versions, it's not uncommon to see an instance where you need a different version of PHP than the one bundled with the operating system.<br />
<br />
=== Selecting a PHP Version ===<br />
This isn't currently possible to do automatically on Sympl 11 and earlier, there are community-supported work-arounds. Sympl 12 adds support for selectable PHP versions, and this functionality is being back-ported to earlier versions.<br />
<br />
{{Template:Sympl 12 Only}}<br />
To select a PHP version for a specific site, place the PHP major and minor versions (such as '5.6', '7.3' or '8.1') in the file <code>config/php</code> and run <code>sudo sympl-php-configure</code>.<br />
<br />
This will then install the relevant PHP version from [https://deb.sury.org https://deb.sury.org] if required, along with the typical PHP packages, and configure the site to use that PHP version. Note there is a small extra disk space requirement for each extra version of PHP installed.<br />
<br />
If other PHP modules/extensions are required for the site, their package names can be placed in <code>config/php-modules</code>, and they will be installed automatically the next time <code>sudo sympl-php-configure</code> is run. Package names are the name of the Debian packaged modules without the PHP version, so the <code>php8.1-tidy</code> package would be listed in the file as <code>tidy</code>. PHP extensions can also be installed manually using apt.<br />
<br />
All sites default to a pool named 'default' unless specified otherwise in <code>config/php-pool</code>. If you require any configuration changes, or wish to adjust resources for a site, you should configure it with it's own pool. Note that each pool has its own memory requirements and PHP instances standing by, so running a large number of pools will consume more RAM on your server.<br />
<br />
==== .htaccess vs .user.ini ====<br />
<br />
When using the default PHP version (ie: not specifying one) the site will run under the default PHP version for the distribution (ie: PHP 8.2 for Debian Bookworm) using 'mod_apache'. This will parse PHP variables and overrides via the <code>.htaccess</code> file in the web content directory, allowing you to make changes on a per-directory basis.<br />
<br />
Running a site under 'FPM' as the configured sites do means they are only passed the relevant file, so require the same configuration entries in a slightly different format in the file <code>.user.ini</code> file, in the same location as <code>.htaccess</code>.<br />
<br />
If you don't already have a <code>.user.ini</code> file in place, Sympl will automatically create and manage one for you each time <code>sudo sympl-php-configure</code> is run. <br />
<br />
==== PHP Command Line ====<br />
<br />
In some instances, you may need to run the PHP from the command line but need a version other than the default. To do so, rather than using the plain <code>php example.php</code> command, simply append the version, for example <code>php8.1 example.php</code>.<br />
<br />
==== Extended Configuration ====<br />
<br />
Sympl supports a number of other extended configuration options, including selectable user and group that the PHP pool should be executed as, with <code>config/php-user</code> and <code>config/php-group</code> respectively. These default to www-data, but if must exist if they are changed, and cannot be system users (ie: with an ID below 1000).<br />
<br />
As the PHP pool files are managed automatically by Sympl to ensure that PHP continues running, manual changes to the pool configurations will be overwritten on each run.<br />
<br />
If a change to a pool configuration is required, extra configuration lines can be added to <code>/etc/sympl/php/<version>/includes.d/<pool_name>.conf</code>. The pool name is defined as <code>><pool_name>[_<username>[_<groupname>]]</code>> with the username and group being optional if not left on the default.<br />
<br />
==PHP Security==<br />
By default, a number of rules are included in the Apache configuration which limit the access of sites running PHP, preventing a compromised site from accessing content outside the <code>/srv/example.com/public/</code> directory, and setting both a domain-specific temp directory and session directory as <code>/srv/example.com/php_tmp/</code> and <code>/srv/example.com/php_sessions/</code> respectively.<br />
<br />
A default configuration is also in place for the ever-popular [[WordPress]], which prevents PHP files from being accessed or executed from within the upload folder, which tend to be the source of most site compromises.<br />
<br />
These restrictions can be disabled by creating the file <code>/srv/example.com/config/disable-php-security</code>, and running <code>sudo sympl-web-configure</code>.<br />
<br />
===PHP Lockdown===<br />
Also available but not enabled by default is a '[[PHP Lockdown|lockdown]]' configuration, which limits a number of potentially dangerous functions in PHP for ''all sites'' where a PHP version is not selected.<br />
<br />
This can be enabled with the command line...<br />
<br />
'''For Sympl 10.x'''<br />
sudo ln -s /etc/php/7.0/mods-available/sympl-web-lockdown.ini /etc/php/7.0/apache2/conf.d/01-sympl-web-lockdown.ini<br />
sudo service apache2 reload<br />
'''For Sympl 11.x'''<br />
sudo ln -s /etc/php/7.3/mods-available/sympl-web-lockdown.ini /etc/php/7.3/apache2/conf.d/01-sympl-web-lockdown.ini<br />
sudo service apache2 reload<br />
'''For Sympl 12.x'''<br />
sudo ln -s /etc/php/8.2/mods-available/sympl-web-lockdown.ini /etc/php/8.2/apache2/conf.d/01-sympl-web-lockdown.ini<br />
sudo service apache2 reload<br />
<br />
Note that this will significantly restrict PHP access, and will affect all sites on the same server, so you should confirm that all sites work as expected once this has been run.<br />
<br />
==Serving the Same Content on Multiple Domains.==<br />
In some cases you may want to accept traffic for and serve the same content for multiple domains, such as [[WordPress Multi-site|WordPress multi-site]] configurations.<br />
<br />
Both of these assume you have the main site already configured and working.<br />
<br />
===Aliasing the Whole Domain===<br />
The most simple option is to alias the whole domain. This will result in the whole configuration including other services such as email, SSL certificates, and FTP sites all sharing the same domain.<br />
<br />
To do this, you only need to create a [[Symbolic Link|symbolic link]] to the directory of the site you want to alias. Aliasing <code>'''''example.org'''''</code> (new domain) to <code>'''''example.com'''''</code> (existing domain) you would use<br />
ln -s /srv/'''''example.com''''' /srv/'''''example.org'''''<br />
<br />
===Aliasing the Web Content Only===<br />
Slightly more complicated, but more flexible is to alias only the <code>public/</code> or <code>public/htdocs/</code> directory. This allows separate email, SSL certificates and individual, which don't reference the main domain. Some sites access content at the directory above <code>htdocs/</code>, in which case you should link at the <code>public/</code> point, otherwise <code>public/htdocs/</code> is usually preferable as it provides separate logging and allows individual FTP access.<br />
<br />
In the examples below, <code>example.com</code> is the site which already exists, and <code>example.org</code> is the new domain.<br />
<br />
====Aliasing public/htdocs/ Only====<br />
mkdir -p /srv/example.org/public<br />
ln -s /srv/example.com/public/htdocs /srv/example.org/public/htdocs<br />
touch /srv/example.org/config/disable-php-security<br />
<br />
====Aliassing public/ and Subdirectories====<br />
mkdir -p /srv/example.org<br />
ln -s /srv/example.com/public /srv/example.org/public<br />
touch /srv/example.org/config/disable-php-security<br />
<br />
====A Note on PHP Security====<br />
By default, PHP processes are restricted to the specific <code>public/</code> directory. This is fine in normal use, but as the links created above are resolved to their targets, they don't match the paths expected and will cause PHP errors. As a workaround, creating the <code>config/disable-php-security</code> file for the new alias disables this restriction, slightly reducing the security of the sites.<br />
<br />
==Serving Content on an Alternate IP Address==<br />
<blockquote>Note that the IP addresses must be valid IPs allocated and routed to your server for this to function.</blockquote>By default, Sympl uses the primary IP addresses (both IPv4 and IPv6) to serve content on. To override this and serve content via another IP address, add the IPs to <code>/srv/'''''example.com'''''/config/ip</code>, followed by <code>sudo sympl-configure-ips</code> to automatically add the IP addresses to the relevant interface, and <code>sudo sympl-configure-ips</code> to adjust the apache configuration to use the new IPs, at which point you should update the DNS for the domain.<br />
<br />
==Enforcing HTTPS==<br />
By default, Sympl will attempt to download a [[Let's Encrypt]] [[SSL Certificate|SSL certificate]] for each site automatically, and will then adjust the Apache configuration to enable it.<br />
<br />
In many cases you will likely want to enforce HTTPS usage on a domain to ensure end-to-end security, and this can be done easily by creating the file <code>/srv/'''''example.com'''''/config/ssl-only</code>.<br />
<br />
This change will take effect automatically within the next hour, but requires a working certificate.<br />
<br />
===HTTP Strict Transport Security (HSTS)===<br />
Once SSL has been enforced, you may also want to ensure users only ever access the site via HTTPS. This can be done by enabling [[HTTP Strict Transport Security|HSTS]], which instructs the users browser to only connect via HTTPS for the next six months.<br />
<br />
You should ensure the site is working properly via HTTPS before enabling this function, but once done, create the file <code>/srv/'''''example.com'''''/config/hsts</code> and the configuration will be updated within the next hour.<br />
<br />
==Redirecting to a Preferred Domain==<br />
In the event you want to force all traffic to the same domain name, this can be done with an [[Apache Rewrites|Apache rewrite]]. This this example, we want to ensure the domain being used is always <code>www.'''''example.com'''''</code>, preventing anyone from using <code>'''''example.com'''''</code> without the <code>www.</code>.<br />
<br />
To do this, you would create a file named <code>.htaccess</code> in the <code>htdocs/</code> directory with this content:<br />
RewriteEngine on<br />
RewriteCond %{HTTP_HOST} !^www.*$ [NC]<br />
RewriteRule ^(.*)$ <nowiki>http://www.%{HTTP_HOST}/$1</nowiki> [R=302,L]<br />
What this set of rules do is:<br />
<br />
#Enable the rewriting of content.<br />
#If the hostname being used does not start with 'www.' (case insensitive)<br />
#Temporarily redirect the request to the same hostname but with 'www.' added and don't process any rules.<br />
<br />
Once this is working as expected, you can change the <code>R=302</code> to <code>R=301</code> to swap the temporary redirect to a permanent one which will be cached by the browser.<blockquote>More information is available at ''[[Apache Rewrites]]''.</blockquote><br />
<br />
<br />
<br />
==Filesystem Permissions==<br />
By default, Sympl adjusts the permissions of files and directories in <code>/srv/'''''example.com'''''/public</code> to ensure web applications can update themselves correctly, and FTP users can make changes as desired.<br />
<br />
This defaults to changing the files and directories to be readable, writable, and owned by the <code>www-data</code> user and the <code>www-data</code> group (which the <code>sympl</code> user is a member of). These defaults can be changed by placing the name or ID of the desired user and group into <code>config/public-user</code> and <code>config/public-group</code>.<br />
<br />
This functionality can be coupled with individual PHP instances for each site (not yet implemented in Sympl) or can be disabled on each domain by creating the file <code>/srv/'''''example.com'''''/config/disable-filesystem-security</code>.<blockquote>See ''[[Filesystem Security]]'' for more information.</blockquote><br />
<br />
==Logging==<br />
By default, the Apache logs are written to <code>/srv/'''''example.com'''''/public/logs</code>, named as either <code>access.log</code> and <code>error.log</code> for HTTP requests, and <code>ssl_access.log</code> and <code>ssl_error.log</code> for HTTPS.<br />
<br />
These are automatically rotated daily, and compressed after two days.<br />
<br />
For any sites being served with [[Mass Hosting|mass hosting]], the logs can be found at <code>/var/log/apache2/zz-mass-hosting.access.log</code> and <code>/var/log/apache2/zz-mass-hosting.error.log</code> .<br />
<br />
Logging for any other traffic is written to <code>/var/log/apache2/other_vhosts_access.log</code>, with any errors for Apache itself at <code>/var/log/apache2/error.log</code>.<br />
<br />
==Web Statistics==<br />
Basic traffic statistics can be optionally generated for the domain from the web logs using [[AWFFull]] (or [[Webalizer]] on Sympl 10 and older), and are written to <code>/srv/'''''example.com'''''/public/htdocs/stats</code>, making them available at <code>https://'''''example.com'''''/stats</code>. <br />
<br />
To trigger the generation, create a file at <code>/srv/'''''example.com'''''/config/stats</code>, and they will be generated automatically overnight for the previous day(s).<br />
<br />
As they contain potentially sensitive information (i.e. client IPs), they are automatically protected by a username and password. To access them you must create a username and password in <code>config/stats-htaccess</code> using <code>htpasswd</code>:<blockquote>'''Note:''' If the file already exists, you should omit the -c parameter or a fresh configuration file will be created and overwrite anything there.</blockquote><br />
htpasswd -c /srv/'''''example.com'''''/config/stats-htaccess '''''username'''''<br />
You will be prompted for a password and confirmation, and you will then be able to log in.<br />
<br />
A template for Webalizer will automatically be written to <code>config/webalizer.conf</code> when the statistics are created, and this can be edited as desired.<br />
<br />
==CGI Scripts==<br />
CGI Scripts are executable code of some kind (binaries or scripts) which are run directly on the operating system, and return the content for a page. Due to them being executable they can be a security risk, so caution should be taken when using them. Usage of CGI Scripts has mostly been supplanted by [[PHP]], however some legacy code <br />
<br />
To use CGI Scripts on your domain, you should copy them to <code>/srv/'''''example.com'''''/public/cgi-bin/</code> and they will then be served at <code>http://'''''example.com'''''/cgi-bin/</code> as long as the files are set executable. Non-executable files will result in an error message rather than serving the content of the file.<br />
<br />
Any files in the <code>public/cgi-bin</code> will not have their permissions updated by <code>sympl-filesystem-security</code>, so it is up to the user to ensure they are set securely, and readable only by the relevant users. Typically they are not be expected to be writable.<br />
<br />
==Custom Additions to the Apache Configuration==<br />
For sites with individual configuration files, custom additions can be made to the Apache configuration by adding files with the <code>.conf</code> extension to <code>/srv/'''''example.com'''''/conf/apache.d/</code>. These will be read when Apache is reloaded or started, and can be used to make changes to the configuration without using <code>.htaccess</code> files.<br />
<br />
The configuration can be tested with <code>sudo apachectl -t</code> and Apache reloaded with <code>sudo service apache2 reload</code>.<br />
<br />
Extreme care should be taken when using this feature, as an invalid configuration will prevent Apache from starting, as as such is considered a feature for advanced users only.<br />
<br />
==Further Modifying the Apache Configuration==<br />
The majority of typical changes to the Apache configuration can be made via relevant <code>.htaccess</code> files, with most of others available via <code>conf/apache.d/</code>.<br />
<br />
In the event you need to make custom changes to the Apache configuration for an individual site, configuration files can be found in <code>/etc/apache/sites-enabled</code>. Note that if you do make any changes, the configuration will no longer be managed by Sympl and it won't make any changes if the templates are updated. If you want to revert to a Sympl generated configuration for a specific domain, you can do this with <code>sudo sympl-web-configure --verbose '''''example.com'''''</code><br />
<br />
If you want to update the configuration of all sites, then you can edit the templates used to generate the Apache configurations, but you should take care when making any changes to ensure the result is valid. These can be found in <code>/etc/sympl/apache.d</code>, and the existing templated configurations can be regenerated with <code>sudo sympl-web-configure --verbose</code>. Note that any changes to the template files will prevent the templates from being automatically updated, pause updates to the <code>sympl-web</code> package until <br />
<br />
Finally, if you want to create your own Apache configurations not managed by Sympl you can do, as it will not make any changes to them.<br />
<br />
==Configuration Reference==<br />
<section begin="config" /><br />
{| class="wikitable sortable"<br />
|+<br />
!File or Directory<br />
!Used For<br />
!<br />
|-<br />
|<code>.../config/ip</code><br />
|Contains a list of IP addresses which a website will be bound to. Defaults to the primary IPs (IPv4 and IPv6) of your server.<br />
|[[Website Configuration Reference#Serving Content on an Alternate IP Address.|<small>More...</small>]]<br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/ssl-only</code><br />
|Redirects all non-HTTPS traffic for the site to HTTPS.<br />
|[[Website Configuration Reference#Enforcing HTTPS|<small>More...</small>]]<br />
|-<br />
|<code>.../config/hsts</code><br />
|Enables HSTS for HTTPS sites.<br />
|<small>[[Website Configuration Reference#HTTP Strict Transport Security (HSTS)|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/php</code><br />
|Selects the PHP version the site should be run under. Remove the file to default to the bundled version for your distribution.<br />
|<small>[[Website Configuration Reference#Selecting a PHP Version|More...]]</small><br />
|-<br />
|<code>.../config/php-modules</code><br />
|A list of PHP modules/extension package names for the site which will be installed automatically.<br />
|<small>[[Website Configuration Reference#Selecting a PHP Version|More...]]</small><br />
|-<br />
|<code>.../config/php-pool<br />
|Defines the alphanumeric name of the PHP pool for the site.<br />
|<small>[[Website Configuration Reference#Selecting a PHP Version|More...]]</small><br />
|-<br />
|<code>.../config/php-user</code><br />
|The local system user to run PHP as<br />
|<small>[[Website Configuration Reference#Extended Configuration|More...]]</small><br />
|-<br />
|<code>.../config/php-group</code><br />
|The local group to run PHP as.<br />
|<small>[[Website Configuration Reference#Extended Configuration|More...]]</small><br />
|-<br />
|<code>.../config/disable-php-security</code><br />
|Existence of this file will disable some of the PHP security functions in the automatically generated [[Apache]] configurations.<br />
|<small>[[Website Configuration Reference#PHP Security|More...]]</small><br />
|-<br />
|<code>/etc/sympl/php/<version>/includes.d/<pool_name>.conf</code><br />
|Configuration changes for a specific PHP pool should be placed here.<br />
|<small>[[Website Configuration Reference#Extended Configuration|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/disable-php-security</code><br />
|Existence of this file will disable some of the PHP security functions in the automatically generated [[Apache]] configurations.<br />
|<small>[[Website Configuration Reference#PHP Security|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/disable-filesystem-security</code><br />
|Existence of this file will disable the automatic filesystem security tasks on this domain.<br />
|<small>[[Website Configuration Reference#Filesystem Permissions|More...]]</small><br />
|-<br />
|<code>.../config/public-user</code><br />
|UID or user name of the user to change ownership of the <code>public/</code> directory to. Defaults to www-data.<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
|<code>.../config/public-group</code><br />
|GID or group name of the user to change ownership of the <code>public/</code> directory to. Defaults to www-data.<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/stats</code><br />
|This file enables automatic generation of [[Web Statistics|web stats]] with [[Awffull]]/[[Webalizer]]<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
|<code>.../config/stats-htaccess</code><br />
|A '[[htpasswd]]' format file used to access the [[Web Statistics|web stats]].<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
|<code>.../config/apache.d/'''''example'''''.conf</code><br />
|Apache config files to be included in the site configuration.<br />
|<small>[[Website Configuration Reference#Custom Additions to the Apache Configuration|More...]]</small><br />
|}<section end="config" /><br />
<br />
<blockquote>See also [[Configuration Reference|''Configuration Reference'']] for other configuration files.</blockquote><br />
[[Category:Web]]<br />
[[Category:Reference]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Website_Configuration_Reference&diff=5009Website Configuration Reference2023-06-12T17:14:03Z<p>Kelduum: </p>
<hr />
<div>This page is a detailed breakdown of all the configuration options and files available when configuring website hosting on Sympl.<br />
<br />
As with all the other documentation here, the site <code>'''''example.com'''''</code> will used, and you should substitute this for your domain.<br />
<br />
All configuration for this domain will be in the /srv/example.com/ directory.<br />
<br />
Sympl uses the [[Apache]] web server, along with the relevant version of [[PHP]] for your version of [[Debian]], along with the typical PHP extensions. See [[Supported PHP Versions]].<br />
<br />
==Getting Started==<br />
The files for example.com are in the <code>/srv/'''''example.com'''''/public/htdocs</code> directory which is the site root.<br />
<br />
*If this directory doesn't exist, is empty, or has no <code>index.php</code> or <code>index.html</code>, the default page will be served, mentioning there is no content on the site.<br />
*The content in the directory will be served for both www.example.com and example.com, so theres no need to prefix the domain with www.<br />
*If you want to serve different content for www.example.com and example.com, you can create /srv/www.example.com as a separate directory.<br />
*Within an hour of the directory creation, a new configuration will [[Sympl-web-configure|automatically be created]] for Apache.<br />
<br />
More detailed information about how Sympl serves content can be found at ''[[How Web Hosting Works on Sympl]]''.<br />
<br />
==Testing Your Sites==<br />
New sites can be tested before they are made live using the 'testing' domains. If your hosting provider provides a wildcard DNS entry on your server pointing to its hostname (and the [[Default Site|default site]] is set to match), then sites can be accessed via this method.<br />
<br />
You can confirm if this is the case using <code>dig</code> or a similar tool - if your server is named <code>'''''server.example.host'''''</code>, if you run <code>dig +short randomname.'''''server.example.host'''''</code> and get a response with the server's IP address, then this is the case.<br />
<br />
If so, you can access any of the sites via this method in the format <domain_directory>.testing.<server_hostname>, for example <code>'''''example.com'''''.testing.'''''server.example.host'''''</code>. Note that the <code>www.</code> should not be included in this case.<br />
<br />
Note that this only applies to websites (not email, FTP and similar), and will not work fully in all instances, as some sites will redirect to their expected hostname or similar. If this is the case, you can test by [[Editing Your Hosts File|editing your hosts file]] on your local computer.<br />
<br />
== PHP Configuration ==<br />
<br />
PHP is the scripting language which the popular Content Management Systems and most websites is written in. It's very popular due to it's flexibility and ease of use, which means that the development of PHP moves quickly, with new versions released every year or so.<br />
<br />
With PHP development moving quickly, the Debian release cycle being every two years, and the common need to run sites on older versions, it's not uncommon to see an instance where you need a different version of PHP than the one bundled with the operating system.<br />
<br />
=== Selecting a PHP Version ===<br />
This isn't currently possible to do automatically on Sympl 11 and earlier, there are community-supported work-arounds. Sympl 12 adds support for selectable PHP versions, and this functionality is being back-ported to earlier versions.<br />
<br />
{{Template:Sympl 12 Only}}<br />
To select a PHP version for a specific site, place the PHP major and minor versions (such as '5.6', '7.3' or '8.1') in the file <code>config/php</code> and run <code>sudo sympl-php-configure</code>.<br />
<br />
This will then install the relevant PHP version from [https://deb.sury.org https://deb.sury.org] if required, along with the typical PHP packages, and configure the site to use that PHP version. Note there is a small extra disk space requirement for each extra version of PHP installed.<br />
<br />
If other PHP modules/extensions are required for the site, their package names can be placed in <code>config/php-modules</code>, and they will be installed automatically the next time <code>sudo sympl-php-configure</code> is run. Package names are the name of the Debian packaged modules without the PHP version, so the <code>php8.1-tidy</code> package would be listed in the file as <code>tidy</code>. PHP extensions can also be installed manually using apt.<br />
<br />
All sites default to a pool named 'default' unless specified otherwise in <code>config/php-pool</code>. If you require any configuration changes, or wish to adjust resources for a site, you should configure it with it's own pool. Note that each pool has its own memory requirements and PHP instances standing by, so running a large number of pools will consume more RAM on your server.<br />
<br />
==== .htaccess vs .user.ini ====<br />
<br />
When using the default PHP version (ie: not specifying one) the site will run under the default PHP version for the distribution (ie: PHP 8.2 for Debian Bookworm) using 'mod_apache'. This will parse PHP variables and overrides via the <code>.htaccess</code> file in the web content directory, allowing you to make changes on a per-directory basis.<br />
<br />
Running a site under 'FPM' as the configured sites do means they are only passed the relevant file, so require the same configuration entries in a slightly different format in the file <code>.user.ini</code> file, in the same location as <code>.htaccess</code>.<br />
<br />
If you don't already have a <code>.user.ini</code> file in place, Sympl will automatically create and manage one for you each time <code>sudo sympl-php-configure</code> is run. <br />
<br />
==== Extended Configuration ====<br />
<br />
Sympl supports a number of other extended configuration options, including selectable user and group that the PHP pool should be executed as, with <code>config/php-user</code> and <code>config/php-group</code> respectively. These default to www-data, but if must exist if they are changed, and cannot be system users (ie: with an ID below 1000).<br />
<br />
As the PHP pool files are managed automatically by Sympl to ensure that PHP continues running, manual changes to the pool configurations will be overwritten on each run.<br />
<br />
If a change to a pool configuration is required, extra configuration lines can be added to <code>/etc/sympl/php/<version>/includes.d/<pool_name>.conf</code>. The pool name is defined as <code>><pool_name>[_<username>[_<groupname>]]</code>> with the username and group being optional if not left on the default.<br />
<br />
==PHP Security==<br />
By default, a number of rules are included in the Apache configuration which limit the access of sites running PHP, preventing a compromised site from accessing content outside the <code>/srv/example.com/public/</code> directory, and setting both a domain-specific temp directory and session directory as <code>/srv/example.com/php_tmp/</code> and <code>/srv/example.com/php_sessions/</code> respectively.<br />
<br />
A default configuration is also in place for the ever-popular [[WordPress]], which prevents PHP files from being accessed or executed from within the upload folder, which tend to be the source of most site compromises.<br />
<br />
These restrictions can be disabled by creating the file <code>/srv/example.com/config/disable-php-security</code>, and running <code>sudo sympl-web-configure</code>.<br />
<br />
===PHP Lockdown===<br />
Also available but not enabled by default is a '[[PHP Lockdown|lockdown]]' configuration, which limits a number of potentially dangerous functions in PHP for ''all sites'' where a PHP version is not selected.<br />
<br />
This can be enabled with the command line...<br />
<br />
'''For Sympl 10.x'''<br />
sudo ln -s /etc/php/7.0/mods-available/sympl-web-lockdown.ini /etc/php/7.0/apache2/conf.d/01-sympl-web-lockdown.ini<br />
sudo service apache2 reload<br />
'''For Sympl 11.x'''<br />
sudo ln -s /etc/php/7.3/mods-available/sympl-web-lockdown.ini /etc/php/7.3/apache2/conf.d/01-sympl-web-lockdown.ini<br />
sudo service apache2 reload<br />
'''For Sympl 12.x'''<br />
sudo ln -s /etc/php/8.2/mods-available/sympl-web-lockdown.ini /etc/php/8.2/apache2/conf.d/01-sympl-web-lockdown.ini<br />
sudo service apache2 reload<br />
<br />
Note that this will significantly restrict PHP access, and will affect all sites on the same server, so you should confirm that all sites work as expected once this has been run.<br />
<br />
==Serving the Same Content on Multiple Domains.==<br />
In some cases you may want to accept traffic for and serve the same content for multiple domains, such as [[WordPress Multi-site|WordPress multi-site]] configurations.<br />
<br />
Both of these assume you have the main site already configured and working.<br />
<br />
===Aliasing the Whole Domain===<br />
The most simple option is to alias the whole domain. This will result in the whole configuration including other services such as email, SSL certificates, and FTP sites all sharing the same domain.<br />
<br />
To do this, you only need to create a [[Symbolic Link|symbolic link]] to the directory of the site you want to alias. Aliasing <code>'''''example.org'''''</code> (new domain) to <code>'''''example.com'''''</code> (existing domain) you would use<br />
ln -s /srv/'''''example.com''''' /srv/'''''example.org'''''<br />
<br />
===Aliasing the Web Content Only===<br />
Slightly more complicated, but more flexible is to alias only the <code>public/</code> or <code>public/htdocs/</code> directory. This allows separate email, SSL certificates and individual, which don't reference the main domain. Some sites access content at the directory above <code>htdocs/</code>, in which case you should link at the <code>public/</code> point, otherwise <code>public/htdocs/</code> is usually preferable as it provides separate logging and allows individual FTP access.<br />
<br />
In the examples below, <code>example.com</code> is the site which already exists, and <code>example.org</code> is the new domain.<br />
<br />
====Aliasing public/htdocs/ Only====<br />
mkdir -p /srv/example.org/public<br />
ln -s /srv/example.com/public/htdocs /srv/example.org/public/htdocs<br />
touch /srv/example.org/config/disable-php-security<br />
<br />
====Aliassing public/ and Subdirectories====<br />
mkdir -p /srv/example.org<br />
ln -s /srv/example.com/public /srv/example.org/public<br />
touch /srv/example.org/config/disable-php-security<br />
<br />
====A Note on PHP Security====<br />
By default, PHP processes are restricted to the specific <code>public/</code> directory. This is fine in normal use, but as the links created above are resolved to their targets, they don't match the paths expected and will cause PHP errors. As a workaround, creating the <code>config/disable-php-security</code> file for the new alias disables this restriction, slightly reducing the security of the sites.<br />
<br />
==Serving Content on an Alternate IP Address==<br />
<blockquote>Note that the IP addresses must be valid IPs allocated and routed to your server for this to function.</blockquote>By default, Sympl uses the primary IP addresses (both IPv4 and IPv6) to serve content on. To override this and serve content via another IP address, add the IPs to <code>/srv/'''''example.com'''''/config/ip</code>, followed by <code>sudo sympl-configure-ips</code> to automatically add the IP addresses to the relevant interface, and <code>sudo sympl-configure-ips</code> to adjust the apache configuration to use the new IPs, at which point you should update the DNS for the domain.<br />
<br />
==Enforcing HTTPS==<br />
By default, Sympl will attempt to download a [[Let's Encrypt]] [[SSL Certificate|SSL certificate]] for each site automatically, and will then adjust the Apache configuration to enable it.<br />
<br />
In many cases you will likely want to enforce HTTPS usage on a domain to ensure end-to-end security, and this can be done easily by creating the file <code>/srv/'''''example.com'''''/config/ssl-only</code>.<br />
<br />
This change will take effect automatically within the next hour, but requires a working certificate.<br />
<br />
===HTTP Strict Transport Security (HSTS)===<br />
Once SSL has been enforced, you may also want to ensure users only ever access the site via HTTPS. This can be done by enabling [[HTTP Strict Transport Security|HSTS]], which instructs the users browser to only connect via HTTPS for the next six months.<br />
<br />
You should ensure the site is working properly via HTTPS before enabling this function, but once done, create the file <code>/srv/'''''example.com'''''/config/hsts</code> and the configuration will be updated within the next hour.<br />
<br />
==Redirecting to a Preferred Domain==<br />
In the event you want to force all traffic to the same domain name, this can be done with an [[Apache Rewrites|Apache rewrite]]. This this example, we want to ensure the domain being used is always <code>www.'''''example.com'''''</code>, preventing anyone from using <code>'''''example.com'''''</code> without the <code>www.</code>.<br />
<br />
To do this, you would create a file named <code>.htaccess</code> in the <code>htdocs/</code> directory with this content:<br />
RewriteEngine on<br />
RewriteCond %{HTTP_HOST} !^www.*$ [NC]<br />
RewriteRule ^(.*)$ <nowiki>http://www.%{HTTP_HOST}/$1</nowiki> [R=302,L]<br />
What this set of rules do is:<br />
<br />
#Enable the rewriting of content.<br />
#If the hostname being used does not start with 'www.' (case insensitive)<br />
#Temporarily redirect the request to the same hostname but with 'www.' added and don't process any rules.<br />
<br />
Once this is working as expected, you can change the <code>R=302</code> to <code>R=301</code> to swap the temporary redirect to a permanent one which will be cached by the browser.<blockquote>More information is available at ''[[Apache Rewrites]]''.</blockquote><br />
<br />
<br />
<br />
==Filesystem Permissions==<br />
By default, Sympl adjusts the permissions of files and directories in <code>/srv/'''''example.com'''''/public</code> to ensure web applications can update themselves correctly, and FTP users can make changes as desired.<br />
<br />
This defaults to changing the files and directories to be readable, writable, and owned by the <code>www-data</code> user and the <code>www-data</code> group (which the <code>sympl</code> user is a member of). These defaults can be changed by placing the name or ID of the desired user and group into <code>config/public-user</code> and <code>config/public-group</code>.<br />
<br />
This functionality can be coupled with individual PHP instances for each site (not yet implemented in Sympl) or can be disabled on each domain by creating the file <code>/srv/'''''example.com'''''/config/disable-filesystem-security</code>.<blockquote>See ''[[Filesystem Security]]'' for more information.</blockquote><br />
<br />
==Logging==<br />
By default, the Apache logs are written to <code>/srv/'''''example.com'''''/public/logs</code>, named as either <code>access.log</code> and <code>error.log</code> for HTTP requests, and <code>ssl_access.log</code> and <code>ssl_error.log</code> for HTTPS.<br />
<br />
These are automatically rotated daily, and compressed after two days.<br />
<br />
For any sites being served with [[Mass Hosting|mass hosting]], the logs can be found at <code>/var/log/apache2/zz-mass-hosting.access.log</code> and <code>/var/log/apache2/zz-mass-hosting.error.log</code> .<br />
<br />
Logging for any other traffic is written to <code>/var/log/apache2/other_vhosts_access.log</code>, with any errors for Apache itself at <code>/var/log/apache2/error.log</code>.<br />
<br />
==Web Statistics==<br />
Basic traffic statistics can be optionally generated for the domain from the web logs using [[AWFFull]] (or [[Webalizer]] on Sympl 10 and older), and are written to <code>/srv/'''''example.com'''''/public/htdocs/stats</code>, making them available at <code>https://'''''example.com'''''/stats</code>. <br />
<br />
To trigger the generation, create a file at <code>/srv/'''''example.com'''''/config/stats</code>, and they will be generated automatically overnight for the previous day(s).<br />
<br />
As they contain potentially sensitive information (i.e. client IPs), they are automatically protected by a username and password. To access them you must create a username and password in <code>config/stats-htaccess</code> using <code>htpasswd</code>:<blockquote>'''Note:''' If the file already exists, you should omit the -c parameter or a fresh configuration file will be created and overwrite anything there.</blockquote><br />
htpasswd -c /srv/'''''example.com'''''/config/stats-htaccess '''''username'''''<br />
You will be prompted for a password and confirmation, and you will then be able to log in.<br />
<br />
A template for Webalizer will automatically be written to <code>config/webalizer.conf</code> when the statistics are created, and this can be edited as desired.<br />
<br />
==CGI Scripts==<br />
CGI Scripts are executable code of some kind (binaries or scripts) which are run directly on the operating system, and return the content for a page. Due to them being executable they can be a security risk, so caution should be taken when using them. Usage of CGI Scripts has mostly been supplanted by [[PHP]], however some legacy code <br />
<br />
To use CGI Scripts on your domain, you should copy them to <code>/srv/'''''example.com'''''/public/cgi-bin/</code> and they will then be served at <code>http://'''''example.com'''''/cgi-bin/</code> as long as the files are set executable. Non-executable files will result in an error message rather than serving the content of the file.<br />
<br />
Any files in the <code>public/cgi-bin</code> will not have their permissions updated by <code>sympl-filesystem-security</code>, so it is up to the user to ensure they are set securely, and readable only by the relevant users. Typically they are not be expected to be writable.<br />
<br />
==Custom Additions to the Apache Configuration==<br />
For sites with individual configuration files, custom additions can be made to the Apache configuration by adding files with the <code>.conf</code> extension to <code>/srv/'''''example.com'''''/conf/apache.d/</code>. These will be read when Apache is reloaded or started, and can be used to make changes to the configuration without using <code>.htaccess</code> files.<br />
<br />
The configuration can be tested with <code>sudo apachectl -t</code> and Apache reloaded with <code>sudo service apache2 reload</code>.<br />
<br />
Extreme care should be taken when using this feature, as an invalid configuration will prevent Apache from starting, as as such is considered a feature for advanced users only.<br />
<br />
==Further Modifying the Apache Configuration==<br />
The majority of typical changes to the Apache configuration can be made via relevant <code>.htaccess</code> files, with most of others available via <code>conf/apache.d/</code>.<br />
<br />
In the event you need to make custom changes to the Apache configuration for an individual site, configuration files can be found in <code>/etc/apache/sites-enabled</code>. Note that if you do make any changes, the configuration will no longer be managed by Sympl and it won't make any changes if the templates are updated. If you want to revert to a Sympl generated configuration for a specific domain, you can do this with <code>sudo sympl-web-configure --verbose '''''example.com'''''</code><br />
<br />
If you want to update the configuration of all sites, then you can edit the templates used to generate the Apache configurations, but you should take care when making any changes to ensure the result is valid. These can be found in <code>/etc/sympl/apache.d</code>, and the existing templated configurations can be regenerated with <code>sudo sympl-web-configure --verbose</code>. Note that any changes to the template files will prevent the templates from being automatically updated, pause updates to the <code>sympl-web</code> package until <br />
<br />
Finally, if you want to create your own Apache configurations not managed by Sympl you can do, as it will not make any changes to them.<br />
<br />
==Configuration Reference==<br />
<section begin="config" /><br />
{| class="wikitable sortable"<br />
|+<br />
!File or Directory<br />
!Used For<br />
!<br />
|-<br />
|<code>.../config/ip</code><br />
|Contains a list of IP addresses which a website will be bound to. Defaults to the primary IPs (IPv4 and IPv6) of your server.<br />
|[[Website Configuration Reference#Serving Content on an Alternate IP Address.|<small>More...</small>]]<br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/ssl-only</code><br />
|Redirects all non-HTTPS traffic for the site to HTTPS.<br />
|[[Website Configuration Reference#Enforcing HTTPS|<small>More...</small>]]<br />
|-<br />
|<code>.../config/hsts</code><br />
|Enables HSTS for HTTPS sites.<br />
|<small>[[Website Configuration Reference#HTTP Strict Transport Security (HSTS)|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/php</code><br />
|Selects the PHP version the site should be run under. Remove the file to default to the bundled version for your distribution.<br />
|<small>[[Website Configuration Reference#Selecting a PHP Version|More...]]</small><br />
|-<br />
|<code>.../config/php-modules</code><br />
|A list of PHP modules/extension package names for the site which will be installed automatically.<br />
|<small>[[Website Configuration Reference#Selecting a PHP Version|More...]]</small><br />
|-<br />
|<code>.../config/php-pool<br />
|Defines the alphanumeric name of the PHP pool for the site.<br />
|<small>[[Website Configuration Reference#Selecting a PHP Version|More...]]</small><br />
|-<br />
|<code>.../config/php-user</code><br />
|The local system user to run PHP as<br />
|<small>[[Website Configuration Reference#Extended Configuration|More...]]</small><br />
|-<br />
|<code>.../config/php-group</code><br />
|The local group to run PHP as.<br />
|<small>[[Website Configuration Reference#Extended Configuration|More...]]</small><br />
|-<br />
|<code>.../config/disable-php-security</code><br />
|Existence of this file will disable some of the PHP security functions in the automatically generated [[Apache]] configurations.<br />
|<small>[[Website Configuration Reference#PHP Security|More...]]</small><br />
|-<br />
|<code>/etc/sympl/php/<version>/includes.d/<pool_name>.conf</code><br />
|Configuration changes for a specific PHP pool should be placed here.<br />
|<small>[[Website Configuration Reference#Extended Configuration|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/disable-php-security</code><br />
|Existence of this file will disable some of the PHP security functions in the automatically generated [[Apache]] configurations.<br />
|<small>[[Website Configuration Reference#PHP Security|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/disable-filesystem-security</code><br />
|Existence of this file will disable the automatic filesystem security tasks on this domain.<br />
|<small>[[Website Configuration Reference#Filesystem Permissions|More...]]</small><br />
|-<br />
|<code>.../config/public-user</code><br />
|UID or user name of the user to change ownership of the <code>public/</code> directory to. Defaults to www-data.<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
|<code>.../config/public-group</code><br />
|GID or group name of the user to change ownership of the <code>public/</code> directory to. Defaults to www-data.<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>.../config/stats</code><br />
|This file enables automatic generation of [[Web Statistics|web stats]] with [[Awffull]]/[[Webalizer]]<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
|<code>.../config/stats-htaccess</code><br />
|A '[[htpasswd]]' format file used to access the [[Web Statistics|web stats]].<br />
|<small>[[Website Configuration Reference#Web Statistics|More...]]</small><br />
|-<br />
|<code>.../config/apache.d/'''''example'''''.conf</code><br />
|Apache config files to be included in the site configuration.<br />
|<small>[[Website Configuration Reference#Custom Additions to the Apache Configuration|More...]]</small><br />
|}<section end="config" /><br />
<br />
<blockquote>See also [[Configuration Reference|''Configuration Reference'']] for other configuration files.</blockquote><br />
[[Category:Web]]<br />
[[Category:Reference]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Template:Sympl_12_Only&diff=5008Template:Sympl 12 Only2023-06-12T16:03:15Z<p>Kelduum: </p>
<hr />
<div><blockquote><div style="border-color: green; border-width: 2px; border-style: solid; background-color: #eeeeee; text-align: center; padding: 5px">This section refers to functionality which is only in <i><b>Sympl 12</b></i>, but will be back-ported to other versions.</div></blockquote><br />
<br />
<includeonly>[[Category:Not Yet Backported]]<includeonly></div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Template:BookwormOnly&diff=5007Template:BookwormOnly2023-06-12T16:02:49Z<p>Kelduum: Kelduum moved page Template:BookwormOnly to Template:Sympl 12 Only</p>
<hr />
<div>#REDIRECT [[Template:Sympl 12 Only]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Template:Sympl_12_Only&diff=5006Template:Sympl 12 Only2023-06-12T16:02:49Z<p>Kelduum: Kelduum moved page Template:BookwormOnly to Template:Sympl 12 Only</p>
<hr />
<div><blockquote><div style="border-color: green; border-width: 2px; border-style: solid; background-color: #eeeeee; text-align: center; padding: 5px">This section refers to functionality which is only in <i><b>Sympl 12</b></i>.</div></blockquote><br />
<br />
<includeonly>[[Category:Not Yet Backported]]<includeonly></div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Template:Sympl_12_Only&diff=5005Template:Sympl 12 Only2023-06-12T16:02:26Z<p>Kelduum: Created page with "<blockquote><div style="border-color: green; border-width: 2px; border-style: solid; background-color: #eeeeee; text-align: center; padding: 5px">This section refers to functi..."</p>
<hr />
<div><blockquote><div style="border-color: green; border-width: 2px; border-style: solid; background-color: #eeeeee; text-align: center; padding: 5px">This section refers to functionality which is only in <i><b>Sympl 12</b></i>.</div></blockquote><br />
<br />
<includeonly>[[Category:Not Yet Backported]]<includeonly></div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Using_OctoDNS_To_Update_DNS&diff=5003Using OctoDNS To Update DNS2023-03-17T09:08:33Z<p>Kelduum: </p>
<hr />
<div>{{Community Documentation}}<br />
<br />
== Introduction==<br />
<br />
The [https://www.mythic-beasts.com/support/api/primary Mythic Beasts DNS API] can be used in conjunction with [https://github.com/github/octodns OctoDNS] to automatically update DNS entries for domains running on Sympl. This guide details the steps required to configure this.<br />
<br />
'''This guide assumes that the appropriate domains are using Mythic Beasts to provide Primary DNS service, and the domain has an appropriate API password configured.'''<br />
<br />
== Install OctoDNS ==<br />
<br />
sudo apt install python3-venv && \<br />
mkdir -p /home/sympl/dns && \<br />
python3 -m venv /home/sympl/dns/ && \<br />
/home/sympl/dns/bin/pip3 install pip octodns<br />
<br />
== Create config file ==<br />
<br />
Sample configuration file (should be saved as <code>/home/sympl/dns.yaml</code>)<br />
<br />
---<br />
<br />
providers:<br />
config_example.com:<br />
class: octodns.source.tinydns.TinyDnsFileSource<br />
directory: /srv/example.com/config/dns<br />
default_ttl: 3600<br />
<br />
config_subdomain1.example.com:<br />
class: octodns.source.tinydns.TinyDnsFileSource<br />
directory: /srv/subdomain1.example.com/config/dns<br />
default_ttl: 3600<br />
<br />
config_subdomain2.example.com:<br />
class: octodns.source.tinydns.TinyDnsFileSource<br />
directory: /srv/subdomain2.example.com/config/dns<br />
default_ttl: 3600<br />
<br />
mythicbeasts:<br />
class: octodns.provider.mythicbeasts.MythicBeastsProvider<br />
passwords:<br />
example.com.: 'mythicdnsapipasswordgoeshere'<br />
<br />
zones:<br />
example.com.:<br />
sources:<br />
- config_example.com<br />
- config_subdomain1.example.com<br />
- config_subdomain2.example.com<br />
<br />
targets:<br />
- mythicbeasts<br />
<br />
== Create script to cleanup published changes to remove DNS server entries ==<br />
<br />
Add the following cleanup script <code>/home/sympl/dns-cleanup.py</code><br />
<br />
#!/usr/bin/python3<br />
<br />
import requests<br />
from pprint import pprint<br />
<br />
from yaml import load, dump<br />
try:<br />
from yaml import load, CLoader as Loader, CDumper as Dumper<br />
except ImportError:<br />
from yaml import Loader, Dumper<br />
<br />
def doRequest(values):<br />
response = requests.post(url, data = values)<br />
responseContents = response.text<br />
return responseContents<br />
<br />
with open('/home/sympl/dns.yaml', 'r') as yamlfile:<br />
yamldoc = load(yamlfile)<br />
<br />
#pprint(yamldoc)<br />
<br />
url = 'https://dnsapi.mythic-beasts.com/'<br />
<br />
for domain in yamldoc['providers']['mythicbeasts']['passwords'].keys():<br />
<br />
yourDomain = domain.strip("'").rstrip(".")<br />
yourDomainAPIPass = yamldoc['providers']['mythicbeasts']['passwords'][domain].strip("'")<br />
<br />
print("Cleaning up '" + yourDomain + "'")<br />
<br />
values = {<br />
'domain' : yourDomain,<br />
'password' : yourDomainAPIPass,<br />
'command' : 'LIST'<br />
}<br />
<br />
responseContents=doRequest(values)<br />
<br />
toDelete = False<br />
values['command']=[]<br />
<br />
for line in responseContents.splitlines():<br />
elements = line.split()<br />
if elements[2]=="NS" and "ns.bytemark.co.uk." in elements[3]:<br />
toDelete=True<br />
values['command'].append("DELETE " + line)<br />
<br />
if toDelete:<br />
responseContents=doRequest(values)<br />
print(responseContents)<br />
else:<br />
print("Nothing to delete")<br />
<br />
== Update Bytemark upload file ==<br />
<br />
Add the following to <code>/root/BytemarkDNS/upload</code> immediately before the <code>exit 0</code> line at the end.<br />
<br />
# BEGIN Run OctoDNS and clean up<br />
. /home/sympl/dns/bin/activate<br />
PATH=$PATH:/home/sympl/dns/bin<br />
octodns-sync --config-file=/home/sympl/dns.yaml --doit --force<br />
/home/sympl/dns-cleanup.py<br />
# END Run OctoDNS and clean up<br />
<br />
Now, whenever <code>sympl-dns-generate</code> is run, it will upload changes using the Mythic Beasts API. When creating new domains, update the configuration file and then manually run <code>sympl-dns-generate</code>.<br />
<br />
[[Category:DNS]]<br />
[[Category:How To]]<br />
[[Category:Stub]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Installing_Sympl&diff=5002Installing Sympl2023-03-15T23:30:21Z<p>Kelduum: Updated URL to redirector which then</p>
<hr />
<div>There are a few ways of installing Sympl. You will need a [[Debian]] or [[Raspberry Pi OS]] server running Stretch (9) or Buster (10), and root access to the server. We suggest the server is freshly re-imaged, with only minimal packages installed on it and a correctly configured hostname.<br />
<br />
==Imaged Install==<br />
If you're using a virtual server from [https://www.mythic-beasts.com Mythic Beasts], you can use their automatic installer to install Sympl and set most things up for you.<blockquote>See ''[[Installing Sympl on Mythic Beasts]]'' for more information.</blockquote><br />
<br />
==Automatic Install==<br />
There is a basic auto-install script which can be used to install Sympl with minimal intervention and point the user to important resources.<br />
<br />
===Install Stable/Production Version===<br />
<pre>wget https://gitlab.com/sympl.io/install/-/raw/master/install.sh</pre><br />
<pre>bash install.sh</pre><br /><br />
===Install Beta/Testing Version===<br />
<pre>wget https://gitlab.com/sympl.io/install/-/raw/master/install.sh</pre><br />
<pre>bash install.sh --testing</pre><br />
<br />
===Non Interactive Install===<br />
The install script supports a non-interactive install, with the <code>--noninteractive</code> switch.<br />
<br />
This disables the normal 5 second delay before installing.<br />
<br />
If using this in an automated script, please ensure that users are pointed to the URL [https://wiki.sympl.host/Get_Started https://wiki.sympl.io/Get_Started] and are made aware of the file <code>README_SYMPL.txt</code> in the root adn sympl users home directories for documentation, and strongly suggest they update the password for the <code>sympl</code> user as soon as possible.<br />
<br />
==Manual Install==<br />
<br />
Alternatively, you can install manually:<br />
<br />
<pre>wget -qO- http://mirror.mythic-beasts.com/mythic/support@mythic-beasts.com.gpg.key | apt-key add -</pre><br />
<pre>echo deb http://packages.mythic-beasts.com/mythic/ $(grep '^VERSION_CODENAME' /etc/os-release | cut -d'=' -f2) main > /etc/apt/sources.list.d/sympl_mythic-beasts.list</pre><br />
<pre>apt-get update</pre><br />
<pre>apt-get install --install-recommends sympl-core</pre><br />
<br />
You will be prompted for a number of things during the install. Depending on the state of your system, some of these may not be asked or may be in another order: <br />
<br />
{| class="wikitable"<br />
|-<br />
!Prompt!!Answer<br />
|-<br />
|Configuring roundcube-core: Configure database for roundcube with dbconfig-common?||<code>Yes</code><br />
|-<br />
|Configuring roundcube-core: Database type to be used by roundcube||<code>MySQL</code><br />
|-<br />
|Configuring roundcube-core: Host running the server for roundcube||<code>localhost</code><br />
|-<br />
|Configuring roundcube-core: Password of the database’s administrative user||Leave Blank<br />
|-<br />
|Configuring roundcube-core: MySQL application password for roundcube||Leave Blank<br />
|-<br />
|User preference (Leave blank to generate a random password)||Leave Blank<br />
|-<br />
|Configuring phpmyadmin: Configure database for phpmyadmin with dbconfig-common?||<code>Yes</code><br />
|-<br />
|Configuring phpmyadmin: Host running the MySQL server for phpmyadmin||<code>localhost</code><br />
|-<br />
|Configuring phpmyadmin: Web server to reconfigure automatically||<code>apache2</code><br />
|-<br />
|Configuring phpmyadmin: Perform upgrade on database for phpmyadmin with dbconfig-common?||<code>yes</code><br />
|-<br />
|Configuring libc6:amd64: Restart services during package upgrades without asking?||<code>Yes</code><br />
|-<br />
|Configuration file /etc/sysctl.conf modified since installation||<code>Install the package maintainer's version</code><br />
|-<br />
|Configuring openssh-server||<code>Install the package maintainer's version</code><br />
|-<br />
|Configuring grub-pc||<code>Keep the local version currently installed</code><br />
|-<br />
|Configuration file /etc/ntp.conf modified since installation||<code>Keep your currently-installed version</code><br />
|-<br />
|Configuration file /etc/phpmyadmin/config.inc.php modified since installation||<code>Install the package maintainer’s version</code><br />
|-<br />
|Configuring unattended-upgrades||<code>Install the package maintainer’s version</code><br />
|}<br />
<br />
Remember to set the new 'sympl' users password with <code>passwd sympl</code> once you have installed.<br />
<br />
[[Category:Installation]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Alternate_PHP_Versions&diff=5001Alternate PHP Versions2023-03-09T16:12:47Z<p>Kelduum: /* Setting It Up */</p>
<hr />
<div>{{Community Documentation}}<br />
<br />
Sympl only natively supports the Debian-bundled PHP, but with a bit of poking, it's easy to give it support for other PHP versions with PHP-FPM which ''doesn't'' break the usual Sympl stuff.<br />
<br />
== Important Information ==<br />
<br />
This involves using a third-party (not official Debian) repository, which means that security fixes and other changes ''may'' take a little longer to appear in all versions.<br />
<br />
However, the [https://deb.sury.org/ repository below] is maintained by Ondřej Surý, who has been a Debian Developer since 2000, and packaged PHP for Debina since 2005, so it's considered safe in most cases.<br />
<br />
It's also important to note that installing this will mean you have some newer packages than typical, you will not automatically receive security updates, and you may encounter issues with Debian or Sympl if not careful, so '''''this is not fully suitable for production settings'''''.<br />
<br />
== Setting It Up ==<br />
<br />
Set this variable to the required PHP version:<br />
<br />
<code>want_version="'''php8.0'''"</code><br />
<br />
You should then be fine to copy and paste these lines, one at a time...<br />
<br />
<pre><br />
# Get the current version running with mod_php<br />
php_version="$( dpkg -l 'libapache2-mod-php[0-9]*' | grep '^ii' | cut -d '-' -f '3' | awk '{ print $1 }' | sort -u )"<br />
# List the relevant php modules so we install the same ones<br />
php_packages="fpm $( dpkg -l "$php_version*" | grep '^ii' | cut -d '-' -f '2' | awk '{ print $1 }' )"<br />
<br />
# Add sury repo if not already there<br />
if [ ! -f /etc/apt/sources.list.d/php.list ] || [ ! -f /etc/apt/preferences.d/sury-php ]; then<br />
apt update<br />
apt -y install apt-transport-https lsb-release ca-certificates curl<br />
curl -sSLo /usr/share/keyrings/deb.sury.org-php.gpg https://packages.sury.org/php/apt.gpg<br />
sh -c 'echo "deb [signed-by=/usr/share/keyrings/deb.sury.org-php.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list'<br />
fi<br />
apt update<br />
<br />
# Enable apache mod<br />
a2enmod proxy_fcgi<br />
<br />
# Attempt to install php-fpm with the relevant packages<br />
<br />
for package in $php_packages; do<br />
echo ---- $package ----<br />
apt -y install $want_version-$package<br />
done<br />
</pre><br />
<br />
Note that some packages such as <code>php8.0-json</code> are virtual packages, so may not be able to be installed normally. This will usually be okay.<br />
<br />
== Enabling ==<br />
<br />
Set this variable to be the domain you want to swap the PHP version on:<br />
<br />
<code>domain="'''example.com'''"</code><br />
<br />
<code>want_version="'''php8.0'''"</code><br />
<br />
Swap the config to use the new PHP version:<br />
<pre><br />
# Create apache include dir<br />
mkdir -p /srv/$domain/config/apache.d<br />
echo "<br />
<FilesMatch \".+\.ph(ar|p|tml)$\"><br />
SetHandler \"proxy:unix:/run/php/$want_version-fpm.sock|fcgi://localhost\"<br />
</FilesMatch><br />
<FilesMatch \".+\.phps$\"><br />
# Deny access to raw php sources by default<br />
# To re-enable it's recommended to enable access to the files<br />
# only in specific virtual host or directory<br />
Require all denied<br />
</FilesMatch><br />
# Deny access to files without filename (e.g. '.php')<br />
<FilesMatch \"^\.ph(ar|p|ps|tml)$\"><br />
Require all denied<br />
</FilesMatch><br />
" > /srv/$domain/config/apache.d/php-fpm.conf<br />
<br />
# Set the permisions<br />
chown sympl:sympl /srv/$domain/config/apache.d /srv/$domain/config/apache.d/php-fpm.conf<br />
<br />
# Make the new config live<br />
sympl-web-configure ; service apache2 reload</pre><br />
<br />
At this point, a simple <code>phpinfo()</code> on the relevant site should report the relevant PHP version.<br />
<br />
<br />
[[Category:How To]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Alternate_PHP_Versions&diff=5000Alternate PHP Versions2023-03-09T16:12:17Z<p>Kelduum: /* Setting It Up */</p>
<hr />
<div>{{Community Documentation}}<br />
<br />
Sympl only natively supports the Debian-bundled PHP, but with a bit of poking, it's easy to give it support for other PHP versions with PHP-FPM which ''doesn't'' break the usual Sympl stuff.<br />
<br />
== Important Information ==<br />
<br />
This involves using a third-party (not official Debian) repository, which means that security fixes and other changes ''may'' take a little longer to appear in all versions.<br />
<br />
However, the [https://deb.sury.org/ repository below] is maintained by Ondřej Surý, who has been a Debian Developer since 2000, and packaged PHP for Debina since 2005, so it's considered safe in most cases.<br />
<br />
It's also important to note that installing this will mean you have some newer packages than typical, you will not automatically receive security updates, and you may encounter issues with Debian or Sympl if not careful, so '''''this is not fully suitable for production settings'''''.<br />
<br />
== Setting It Up ==<br />
<br />
Set this variable to the required PHP version:<br />
<br />
<code>want_version="'''php8.0'''"</code><br />
<br />
You should then be fine to copy and paste these lines, one at a time...<br />
<br />
<pre><br />
# Get the current version running with mod_php<br />
php_version="$( dpkg -l 'libapache2-mod-php[0-9]*' | grep '^ii' | cut -d '-' -f '3' | awk '{ print $1 }' | sort -u )"<br />
# List the relevant php modules so we install the same ones<br />
php_packages="fpm $( dpkg -l "$php_version*" | grep '^ii' | cut -d '-' -f '2' | awk '{ print $1 }' )"<br />
<br />
# Add sury repo if not already there<br />
if [ ! -f /etc/apt/sources.list.d/php.list ] || [ ! -f /etc/apt/preferences.d/sury-php ]; then<br />
apt update<br />
apt -y install apt-transport-https lsb-release ca-certificates curl<br />
curl -sSLo /usr/share/keyrings/deb.sury.org-php.gpg https://packages.sury.org/php/apt.gpg<br />
sh -c 'echo "deb [signed-by=/usr/share/keyrings/deb.sury.org-php.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list'<br />
fi<br />
apt update<br />
<br />
# Enable apache mod<br />
a2enmod proxy_fcgi<br />
<br />
# Attempt to install php-fpm with the relevant packages<br />
echo ----<br />
for package in $php_packages; do<br />
apt -y install $want_version-$package<br />
done<br />
</pre><br />
<br />
Note that some packages such as <code>php8.0-json</code> are virtual packages, so may not be able to be installed normally. This will usually be okay.<br />
<br />
== Enabling ==<br />
<br />
Set this variable to be the domain you want to swap the PHP version on:<br />
<br />
<code>domain="'''example.com'''"</code><br />
<br />
<code>want_version="'''php8.0'''"</code><br />
<br />
Swap the config to use the new PHP version:<br />
<pre><br />
# Create apache include dir<br />
mkdir -p /srv/$domain/config/apache.d<br />
echo "<br />
<FilesMatch \".+\.ph(ar|p|tml)$\"><br />
SetHandler \"proxy:unix:/run/php/$want_version-fpm.sock|fcgi://localhost\"<br />
</FilesMatch><br />
<FilesMatch \".+\.phps$\"><br />
# Deny access to raw php sources by default<br />
# To re-enable it's recommended to enable access to the files<br />
# only in specific virtual host or directory<br />
Require all denied<br />
</FilesMatch><br />
# Deny access to files without filename (e.g. '.php')<br />
<FilesMatch \"^\.ph(ar|p|ps|tml)$\"><br />
Require all denied<br />
</FilesMatch><br />
" > /srv/$domain/config/apache.d/php-fpm.conf<br />
<br />
# Set the permisions<br />
chown sympl:sympl /srv/$domain/config/apache.d /srv/$domain/config/apache.d/php-fpm.conf<br />
<br />
# Make the new config live<br />
sympl-web-configure ; service apache2 reload</pre><br />
<br />
At this point, a simple <code>phpinfo()</code> on the relevant site should report the relevant PHP version.<br />
<br />
<br />
[[Category:How To]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Alternate_PHP_Versions&diff=4999Alternate PHP Versions2023-03-09T16:10:14Z<p>Kelduum: /* Enabling */</p>
<hr />
<div>{{Community Documentation}}<br />
<br />
Sympl only natively supports the Debian-bundled PHP, but with a bit of poking, it's easy to give it support for other PHP versions with PHP-FPM which ''doesn't'' break the usual Sympl stuff.<br />
<br />
== Important Information ==<br />
<br />
This involves using a third-party (not official Debian) repository, which means that security fixes and other changes ''may'' take a little longer to appear in all versions.<br />
<br />
However, the [https://deb.sury.org/ repository below] is maintained by Ondřej Surý, who has been a Debian Developer since 2000, and packaged PHP for Debina since 2005, so it's considered safe in most cases.<br />
<br />
It's also important to note that installing this will mean you have some newer packages than typical, you will not automatically receive security updates, and you may encounter issues with Debian or Sympl if not careful, so '''''this is not fully suitable for production settings'''''.<br />
<br />
== Setting It Up ==<br />
<br />
Set this variable to the required PHP version:<br />
<br />
<code>want_version="'''php8.0'''"</code><br />
<br />
You should then be fine to copy and paste these lines, one at a time...<br />
<br />
<pre><br />
# Get the current version running with mod_php<br />
php_version="$( dpkg -l 'libapache2-mod-php[0-9]*' | grep '^ii' | cut -d '-' -f '3' | awk '{ print $1 }' | sort -u )"<br />
# List the relevant php modules so we install the same ones<br />
php_packages="fpm $( dpkg -l "$php_version*" | grep '^ii' | cut -d '-' -f '2' | awk '{ print $1 }' )"<br />
<br />
# Add sury repo if not already there<br />
if [ ! -f /etc/apt/sources.list.d/php.list ] || [ ! -f /etc/apt/preferences.d/sury-php ]; then<br />
apt update<br />
apt -y install apt-transport-https lsb-release ca-certificates curl<br />
curl -sSLo /usr/share/keyrings/deb.sury.org-php.gpg https://packages.sury.org/php/apt.gpg<br />
sh -c 'echo "deb [signed-by=/usr/share/keyrings/deb.sury.org-php.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list'<br />
fi<br />
apt update<br />
<br />
# Enable apache mod<br />
a2enmod proxy_fcgi<br />
<br />
# Attempt to install php-fpm with the relevant packages<br />
echo ----<br />
for package in $php_packages; do<br />
apt install $want_version-$package<br />
done<br />
</pre><br />
<br />
Note that some packages such as <code>php8.0-json</code> are virtual packages, so may not be able to be installed normally. This will usually be okay.<br />
<br />
== Enabling ==<br />
<br />
Set this variable to be the domain you want to swap the PHP version on:<br />
<br />
<code>domain="'''example.com'''"</code><br />
<br />
<code>want_version="'''php8.0'''"</code><br />
<br />
Swap the config to use the new PHP version:<br />
<pre><br />
# Create apache include dir<br />
mkdir -p /srv/$domain/config/apache.d<br />
echo "<br />
<FilesMatch \".+\.ph(ar|p|tml)$\"><br />
SetHandler \"proxy:unix:/run/php/$want_version-fpm.sock|fcgi://localhost\"<br />
</FilesMatch><br />
<FilesMatch \".+\.phps$\"><br />
# Deny access to raw php sources by default<br />
# To re-enable it's recommended to enable access to the files<br />
# only in specific virtual host or directory<br />
Require all denied<br />
</FilesMatch><br />
# Deny access to files without filename (e.g. '.php')<br />
<FilesMatch \"^\.ph(ar|p|ps|tml)$\"><br />
Require all denied<br />
</FilesMatch><br />
" > /srv/$domain/config/apache.d/php-fpm.conf<br />
<br />
# Set the permisions<br />
chown sympl:sympl /srv/$domain/config/apache.d /srv/$domain/config/apache.d/php-fpm.conf<br />
<br />
# Make the new config live<br />
sympl-web-configure ; service apache2 reload</pre><br />
<br />
At this point, a simple <code>phpinfo()</code> on the relevant site should report the relevant PHP version.<br />
<br />
<br />
[[Category:How To]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Alternate_PHP_Versions&diff=4998Alternate PHP Versions2023-03-09T16:08:24Z<p>Kelduum: /* Important Information */</p>
<hr />
<div>{{Community Documentation}}<br />
<br />
Sympl only natively supports the Debian-bundled PHP, but with a bit of poking, it's easy to give it support for other PHP versions with PHP-FPM which ''doesn't'' break the usual Sympl stuff.<br />
<br />
== Important Information ==<br />
<br />
This involves using a third-party (not official Debian) repository, which means that security fixes and other changes ''may'' take a little longer to appear in all versions.<br />
<br />
However, the [https://deb.sury.org/ repository below] is maintained by Ondřej Surý, who has been a Debian Developer since 2000, and packaged PHP for Debina since 2005, so it's considered safe in most cases.<br />
<br />
It's also important to note that installing this will mean you have some newer packages than typical, you will not automatically receive security updates, and you may encounter issues with Debian or Sympl if not careful, so '''''this is not fully suitable for production settings'''''.<br />
<br />
== Setting It Up ==<br />
<br />
Set this variable to the required PHP version:<br />
<br />
<code>want_version="'''php8.0'''"</code><br />
<br />
You should then be fine to copy and paste these lines, one at a time...<br />
<br />
<pre><br />
# Get the current version running with mod_php<br />
php_version="$( dpkg -l 'libapache2-mod-php[0-9]*' | grep '^ii' | cut -d '-' -f '3' | awk '{ print $1 }' | sort -u )"<br />
# List the relevant php modules so we install the same ones<br />
php_packages="fpm $( dpkg -l "$php_version*" | grep '^ii' | cut -d '-' -f '2' | awk '{ print $1 }' )"<br />
<br />
# Add sury repo if not already there<br />
if [ ! -f /etc/apt/sources.list.d/php.list ] || [ ! -f /etc/apt/preferences.d/sury-php ]; then<br />
apt update<br />
apt -y install apt-transport-https lsb-release ca-certificates curl<br />
curl -sSLo /usr/share/keyrings/deb.sury.org-php.gpg https://packages.sury.org/php/apt.gpg<br />
sh -c 'echo "deb [signed-by=/usr/share/keyrings/deb.sury.org-php.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list'<br />
fi<br />
apt update<br />
<br />
# Enable apache mod<br />
a2enmod proxy_fcgi<br />
<br />
# Attempt to install php-fpm with the relevant packages<br />
echo ----<br />
for package in $php_packages; do<br />
apt install $want_version-$package<br />
done<br />
</pre><br />
<br />
Note that some packages such as <code>php8.0-json</code> are virtual packages, so may not be able to be installed normally. This will usually be okay.<br />
<br />
== Enabling ==<br />
<br />
Set this variable to be the domain you want to swap the PHP version on:<br />
<br />
<code>domain="'''example.com'''"</code><br />
<code>want_version="'''php8.0'''"</code><br />
<br />
Swap the config to use the new PHP version:<br />
<pre><br />
# Create apache include dir<br />
mkdir -p /srv/$domain/config/apache.d<br />
echo "<br />
<FilesMatch \".+\.ph(ar|p|tml)$\"><br />
SetHandler \"proxy:unix:/run/php/$want_version-fpm.sock|fcgi://localhost\"<br />
</FilesMatch><br />
<FilesMatch \".+\.phps$\"><br />
# Deny access to raw php sources by default<br />
# To re-enable it's recommended to enable access to the files<br />
# only in specific virtual host or directory<br />
Require all denied<br />
</FilesMatch><br />
# Deny access to files without filename (e.g. '.php')<br />
<FilesMatch \"^\.ph(ar|p|ps|tml)$\"><br />
Require all denied<br />
</FilesMatch><br />
" > /srv/$domain/config/apache.d/php-fpm.conf<br />
<br />
# Set the permisions<br />
chown sympl:sympl /srv/$domain/config/apache.d /srv/$domain/config/apache.d/php-fpm.conf<br />
<br />
# Make the new config live<br />
sympl-web-configure ; service apache2 reload</pre><br />
<br />
At this point, a simple <code>phpinfo()</code> on the relevant site should report the relevant PHP version.<br />
<br />
<br />
[[Category:How To]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Alternate_PHP_Versions&diff=4997Alternate PHP Versions2023-03-09T16:07:46Z<p>Kelduum: /* Important Information */</p>
<hr />
<div>{{Community Documentation}}<br />
<br />
Sympl only natively supports the Debian-bundled PHP, but with a bit of poking, it's easy to give it support for other PHP versions with PHP-FPM which ''doesn't'' break the usual Sympl stuff.<br />
<br />
== Important Information ==<br />
<br />
This involves using a third-party (not official Debian) repository, which means that security fixes and other changes ''may'' take a little longer to appear in all versions.<br />
<br />
However, the [https://deb.sury.org/ repository below] is maintained by Ondřej Surý, who has been a Debian Developer since 2000, and packaged PHP for Debina since 2005, so it's considered safe in most cases.<br />
<br />
It's also important to note that installing this will mean you have some newer packages than typical, and you may encounter issues with Debian or Sympl if not careful, so '''''this is not fully suitable for production settings'''''.<br />
<br />
== Setting It Up ==<br />
<br />
Set this variable to the required PHP version:<br />
<br />
<code>want_version="'''php8.0'''"</code><br />
<br />
You should then be fine to copy and paste these lines, one at a time...<br />
<br />
<pre><br />
# Get the current version running with mod_php<br />
php_version="$( dpkg -l 'libapache2-mod-php[0-9]*' | grep '^ii' | cut -d '-' -f '3' | awk '{ print $1 }' | sort -u )"<br />
# List the relevant php modules so we install the same ones<br />
php_packages="fpm $( dpkg -l "$php_version*" | grep '^ii' | cut -d '-' -f '2' | awk '{ print $1 }' )"<br />
<br />
# Add sury repo if not already there<br />
if [ ! -f /etc/apt/sources.list.d/php.list ] || [ ! -f /etc/apt/preferences.d/sury-php ]; then<br />
apt update<br />
apt -y install apt-transport-https lsb-release ca-certificates curl<br />
curl -sSLo /usr/share/keyrings/deb.sury.org-php.gpg https://packages.sury.org/php/apt.gpg<br />
sh -c 'echo "deb [signed-by=/usr/share/keyrings/deb.sury.org-php.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list'<br />
fi<br />
apt update<br />
<br />
# Enable apache mod<br />
a2enmod proxy_fcgi<br />
<br />
# Attempt to install php-fpm with the relevant packages<br />
echo ----<br />
for package in $php_packages; do<br />
apt install $want_version-$package<br />
done<br />
</pre><br />
<br />
Note that some packages such as <code>php8.0-json</code> are virtual packages, so may not be able to be installed normally. This will usually be okay.<br />
<br />
== Enabling ==<br />
<br />
Set this variable to be the domain you want to swap the PHP version on:<br />
<br />
<code>domain="'''example.com'''"</code><br />
<code>want_version="'''php8.0'''"</code><br />
<br />
Swap the config to use the new PHP version:<br />
<pre><br />
# Create apache include dir<br />
mkdir -p /srv/$domain/config/apache.d<br />
echo "<br />
<FilesMatch \".+\.ph(ar|p|tml)$\"><br />
SetHandler \"proxy:unix:/run/php/$want_version-fpm.sock|fcgi://localhost\"<br />
</FilesMatch><br />
<FilesMatch \".+\.phps$\"><br />
# Deny access to raw php sources by default<br />
# To re-enable it's recommended to enable access to the files<br />
# only in specific virtual host or directory<br />
Require all denied<br />
</FilesMatch><br />
# Deny access to files without filename (e.g. '.php')<br />
<FilesMatch \"^\.ph(ar|p|ps|tml)$\"><br />
Require all denied<br />
</FilesMatch><br />
" > /srv/$domain/config/apache.d/php-fpm.conf<br />
<br />
# Set the permisions<br />
chown sympl:sympl /srv/$domain/config/apache.d /srv/$domain/config/apache.d/php-fpm.conf<br />
<br />
# Make the new config live<br />
sympl-web-configure ; service apache2 reload</pre><br />
<br />
At this point, a simple <code>phpinfo()</code> on the relevant site should report the relevant PHP version.<br />
<br />
<br />
[[Category:How To]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Alternate_PHP_Versions&diff=4996Alternate PHP Versions2023-03-09T16:06:59Z<p>Kelduum: Created page with "{{Community Documentation}} Sympl only natively supports the Debian-bundled PHP, but with a bit of poking, it's easy to give it support for other PHP versions with PHP-FPM wh..."</p>
<hr />
<div>{{Community Documentation}}<br />
<br />
Sympl only natively supports the Debian-bundled PHP, but with a bit of poking, it's easy to give it support for other PHP versions with PHP-FPM which ''doesn't'' break the usual Sympl stuff.<br />
<br />
== Important Information ==<br />
<br />
This involves using a third-party (not official Debian) repository, which means that security fixes and other changes *may* take a little longer to appear in all versions.<br />
<br />
However, the [https://deb.sury.org/ repository below] is maintained by Ondřej Surý, who has been a Debian Developer since 2000, and packaged PHP for Debina since 2005, so it's considered safe in most cases.<br />
<br />
It's also important to note that installing this will mean you have some newer packages than typical, and you may encounter issues with Debian or Sympl if not careful, so this is not fully suitable for production settings.<br />
<br />
== Setting It Up ==<br />
<br />
Set this variable to the required PHP version:<br />
<br />
<code>want_version="'''php8.0'''"</code><br />
<br />
You should then be fine to copy and paste these lines, one at a time...<br />
<br />
<pre><br />
# Get the current version running with mod_php<br />
php_version="$( dpkg -l 'libapache2-mod-php[0-9]*' | grep '^ii' | cut -d '-' -f '3' | awk '{ print $1 }' | sort -u )"<br />
# List the relevant php modules so we install the same ones<br />
php_packages="fpm $( dpkg -l "$php_version*" | grep '^ii' | cut -d '-' -f '2' | awk '{ print $1 }' )"<br />
<br />
# Add sury repo if not already there<br />
if [ ! -f /etc/apt/sources.list.d/php.list ] || [ ! -f /etc/apt/preferences.d/sury-php ]; then<br />
apt update<br />
apt -y install apt-transport-https lsb-release ca-certificates curl<br />
curl -sSLo /usr/share/keyrings/deb.sury.org-php.gpg https://packages.sury.org/php/apt.gpg<br />
sh -c 'echo "deb [signed-by=/usr/share/keyrings/deb.sury.org-php.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list'<br />
fi<br />
apt update<br />
<br />
# Enable apache mod<br />
a2enmod proxy_fcgi<br />
<br />
# Attempt to install php-fpm with the relevant packages<br />
echo ----<br />
for package in $php_packages; do<br />
apt install $want_version-$package<br />
done<br />
</pre><br />
<br />
Note that some packages such as <code>php8.0-json</code> are virtual packages, so may not be able to be installed normally. This will usually be okay.<br />
<br />
== Enabling ==<br />
<br />
Set this variable to be the domain you want to swap the PHP version on:<br />
<br />
<code>domain="'''example.com'''"</code><br />
<code>want_version="'''php8.0'''"</code><br />
<br />
Swap the config to use the new PHP version:<br />
<pre><br />
# Create apache include dir<br />
mkdir -p /srv/$domain/config/apache.d<br />
echo "<br />
<FilesMatch \".+\.ph(ar|p|tml)$\"><br />
SetHandler \"proxy:unix:/run/php/$want_version-fpm.sock|fcgi://localhost\"<br />
</FilesMatch><br />
<FilesMatch \".+\.phps$\"><br />
# Deny access to raw php sources by default<br />
# To re-enable it's recommended to enable access to the files<br />
# only in specific virtual host or directory<br />
Require all denied<br />
</FilesMatch><br />
# Deny access to files without filename (e.g. '.php')<br />
<FilesMatch \"^\.ph(ar|p|ps|tml)$\"><br />
Require all denied<br />
</FilesMatch><br />
" > /srv/$domain/config/apache.d/php-fpm.conf<br />
<br />
# Set the permisions<br />
chown sympl:sympl /srv/$domain/config/apache.d /srv/$domain/config/apache.d/php-fpm.conf<br />
<br />
# Make the new config live<br />
sympl-web-configure ; service apache2 reload</pre><br />
<br />
At this point, a simple <code>phpinfo()</code> on the relevant site should report the relevant PHP version.<br />
<br />
<br />
[[Category:How To]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=User_talk:Alphacabbage1&diff=4988User talk:Alphacabbage12022-11-10T16:14:03Z<p>Kelduum: Welcome!</p>
<hr />
<div>'''Welcome to ''Sympl Wiki''!'''<br />
We hope you will contribute much and well.<br />
You will probably want to read the [https://www.mediawiki.org/wiki/Special:MyLanguage/Help:Contents help pages].<br />
Again, welcome and have fun! [[User:Kelduum|Kelduum]] ([[User talk:Kelduum|talk]]) 16:14, 10 November 2022 (UTC)</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=User:Alphacabbage1&diff=4987User:Alphacabbage12022-11-10T16:14:03Z<p>Kelduum: Creating user page for new user.</p>
<hr />
<div>Experimental cabbage designer seeking ten words for a mandatory "bio" ;)</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Sympl:Terms_of_Service&diff=4979Sympl:Terms of Service2022-09-28T16:59:14Z<p>Kelduum: </p>
<hr />
<div>The terms of use for the Sympl Wiki are relatively easy to follow, but unfortunately due to sustained spam attempts, account creation is a little more hassle.<br />
<br />
# One account per person.<br />
# Sympl-related content only.<br />
# If you have an account on the Sympl forum, please try to use a similar username.<br />
# A valid Email address must be used and verified before you can post.<br />
# The SysOp's decision is final.</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Sympl:Terms_of_Service&diff=4978Sympl:Terms of Service2022-09-28T16:59:00Z<p>Kelduum: Created page with "The terms of use for the Sympl Wiki are relatively easy to follow, but unfortunately due to sustained spam attempts, account creation is a little more hassle. 1. One account..."</p>
<hr />
<div>The terms of use for the Sympl Wiki are relatively easy to follow, but unfortunately due to sustained spam attempts, account creation is a little more hassle.<br />
<br />
1. One account per person.<br />
2. Sympl-related content only.<br />
3. If you have an account on the Sympl forum, please try to use a similar username.<br />
4. A valid Email address must be used and verified before you can post.<br />
5. The SysOp's decision is final.</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=User:Kelduum&diff=4975User:Kelduum2022-09-28T10:01:07Z<p>Kelduum: </p>
<hr />
<div>I'm Kelduum, or Paul Cammish, and I'm the maintainer of Sympl.</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Upgrading_Debian_Versions&diff=499Upgrading Debian Versions2022-09-01T11:22:18Z<p>Kelduum: </p>
<hr />
<div>Upgrading the version of Debian on a server running Sympl can be tricky, as initial dependencies and packages on the server can vary. <br />
<br />
== Upgrading from Debian Buster ==<br />
<br />
Upgrading from Debian Buster to Debian Bullseye is relatively straightforward, but we've only been able to test upgrades on servers with Mythic Beasts, so while this may work with other hosting providers we can't support upgrades with them, as the initial server state may conflict.<br />
<br />
If you have a Managed Sympl Server with Mythic Beasts, just contact support and they will be able to handle the update for you.<br />
<br />
As with any significant upgrade, ensure that any sites or software are compatible with the new versions, and that you have full, recent, verified backups.<br />
<br />
The major changes for Sympl in between Debian Buster and Bullseye are:<br />
* PHP7.3 has been updated to PHP7.4, information on the changes are [https://www.php.net/manual/en/migration74.php available on the php.net site].<br />
* Web statistics application Webalizer has been replaced with [https://packages.debian.org/bullseye/awffull AWFFull].<br />
<br />
=== Preparatory Work ===<br />
<br />
First, you should apply any pending updates for the operating system, and Sympl:<br />
<br />
apt -y update && apt -y upgrade && apt -y dist-upgrade && sympl update<br />
<br />
Next, replace the current Sympl sources.list file with one for buster (if you didn't use the Sympl installer or installed it manually, your filenames may vary):<br />
<br />
sed 's|buster|bullseye|g' /etc/apt/sources.list.d/sympl_buster.list > /etc/apt/sources.list.d/sympl_bullseye.list && rm /etc/apt/sources.list.d/sympl_buster.list<br />
<br />
Move the existing distribution sources.list out of the way.<br />
<br />
mv /etc/apt/sources.list /etc/apt/sources.list_buster_$( date +%s )<br />
<br />
Then create a new distribution sources.list with the new distribution codename.<br />
<br />
<nowiki>echo "deb http://mirror.mythic-beasts.com/debian/ bullseye main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bullseye main<br />
<br />
deb http://security.debian.org/debian-security bullseye-security main<br />
deb-src http://security.debian.org/debian-security bullseye-security main<br />
<br />
deb http://mirror.mythic-beasts.com/debian/ bullseye-updates main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bullseye-updates main" > /etc/apt/sources.list</nowiki><br />
<br />
Update the apt data.<br />
<br />
apt update<br />
<br />
Verify there will be enough disk space for the upgrades.<br />
<br />
apt -o APT::Get::Trivial-Only=true full-upgrade<br />
<br />
At this point, if apt mentions theres not going to be enough disk space, then you need to clear some space.<br />
<br />
=== Upgrading ===<br />
<br />
'''''Important'': Beyond this point, services will be disrupted, and you should expect around 30 minutes downtime. There's no going back without restoring backups, so be extra sure you have working backups before continuing.'''<br />
<br />
<br />
Upgrade any packages which don't have new dependencies. When prompted, answer 'yes' to restart services without asking.<br />
<br />
apt -y upgrade --without-new-pkgs<br />
<br />
Update the rest of the packages, including installing new ones. When prompted, answer 'yes' to upgrade the Roundcube database, and 'keep' the modified roundcube configuration file.<br />
<br />
apt -y full-upgrade<br />
<br />
Update a missing dependency:<br />
<br />
apt -y install guile-2.2-libs --only-upgrade<br />
<br />
=== Cleaning Up ===<br />
<br />
Remove any extra packages which are no longer needed:<br />
<br />
apt -y autoremove<br />
<br />
Fix up the MySQL and PureFTPd services:<br />
<br />
systemctl disable mysql.service<br />
systemctl enable mysql.service<br />
rm /etc/pure-ftpd/auth/*<br />
ln -s ../conf/ExtAuth /etc/pure-ftpd/auth/60Ext <br />
<br />
Upgrade any web stats to the new format<br />
<br />
find /srv/*/config -maxdepth 1 -mindepth 1 -name 'stats' | sed 's|/config/stats||' | while read path ; do awffull_history_regen --dir "$path/public/htdocs/stats" > "$path/config/.webalizer.hist"; done<br />
<br />
Restart the server to apply the new kernel.<br />
<br />
shutdown -r now<br />
<br />
=== Confirming The Upgrade ===<br />
<br />
Reconnect to the server, and check it's reporting it's running on Debian 11, with a 5.10 Kernel<br />
<br />
lsb_release -a ; uname -a <br />
<br />
List the versions of the sympl packages, each one should start '<code>11.</code>'<br />
<br />
dpkg -l 'sympl-*'<br />
<br />
Run the watchdog, and check it reports no issues.<br />
<br />
sympl-monit<br />
<br />
It should take a few seconds to run but will return immediately with no output if it's already running or load is too high. You should be okay to repeat until you get a result and everything should say 'PASSED'<br />
<br />
Finally, manually check sites look as expected.<br />
<br />
== Upgrading from Debian Stretch ==<br />
<br />
At present we don't have enough data to confirm if a server running [[Debian]] Stretch with Sympl can be safely upgraded to Debian Buster, therefore it's not something we can support at present.<br />
<br />
For this reason, we suggest migrating your configuration to a ''new'' server running a more modern version, rather than upgrading the current one.<br />
<br />
[[Category:Upgrading]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Upgrading_Debian_Versions&diff=498Upgrading Debian Versions2022-09-01T11:13:27Z<p>Kelduum: /* Upgrading from Debian Buster */</p>
<hr />
<div>Upgrading the version of Debian on a server running Sympl can be tricky, as initial dependencies and packages on the server can vary. <br />
<br />
== Upgrading from Debian Buster ==<br />
<br />
Upgrading from Debian Buster to Debian Bullseye is relatively straightforward, but we've only been able to test upgrades on servers with Mythic Beasts, so while this may work with other hosting providers we can't support upgrades with them, as the initial server state may conflict.<br />
<br />
As with any significant upgrade, ensure that any sites or software are compatible with the new versions, and you have full, recent, verified backups.<br />
<br />
The major changes for Sympl in between Debian Buster and Bullseye are:<br />
* PHP7.3 has been updated to PHP7.4, information on the changes are [https://www.php.net/manual/en/migration74.php available on the php.net site].<br />
* Web statistics application Webalizer has been replaced with [https://packages.debian.org/bullseye/awffull AWFFull].<br />
<br />
=== Preparatory Work ===<br />
<br />
First, you should apply any pending updates for the operating system, and Sympl:<br />
<br />
apt -y update && apt -y upgrade && apt -y dist-upgrade && sympl update<br />
<br />
Next, replace the current Sympl sources.list file with one for buster (if you didn't use the Sympl installer or installed it manually, your filenames may vary):<br />
<br />
sed 's|buster|bullseye|g' /etc/apt/sources.list.d/sympl_buster.list > /etc/apt/sources.list.d/sympl_bullseye.list && rm /etc/apt/sources.list.d/sympl_buster.list<br />
<br />
Move the existing distribution sources.list out of the way.<br />
<br />
mv /etc/apt/sources.list /etc/apt/sources.list_buster_$( date +%s )<br />
<br />
Then create a new distribution sources.list with the new distribution codename.<br />
<br />
<nowiki>echo "deb http://mirror.mythic-beasts.com/debian/ bullseye main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bullseye main<br />
<br />
deb http://security.debian.org/debian-security bullseye-security main<br />
deb-src http://security.debian.org/debian-security bullseye-security main<br />
<br />
deb http://mirror.mythic-beasts.com/debian/ bullseye-updates main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bullseye-updates main" > /etc/apt/sources.list</nowiki><br />
<br />
Update the apt data.<br />
<br />
apt update<br />
<br />
Verify there will be enough disk space for the upgrades.<br />
<br />
apt -o APT::Get::Trivial-Only=true full-upgrade<br />
<br />
At this point, if apt mentions theres not going to be enough disk space, then you need to clear some space.<br />
<br />
=== Upgrading ===<br />
<br />
'''''Important'': Beyond this point, services will be disrupted, and you should expect around 30 minutes downtime. There's no going back without restoring backups, so be extra sure you have working backups before continuing.'''<br />
<br />
<br />
Upgrade any packages which don't have new dependencies. When prompted, answer 'yes' to restart services without asking.<br />
<br />
apt -y upgrade --without-new-pkgs<br />
<br />
Update the rest of the packages, including installing new ones. When prompted, answer 'yes' to upgrade the Roundcube database, and 'keep' the modified roundcube configuration file.<br />
<br />
apt -y full-upgrade<br />
<br />
Update a missing dependency:<br />
<br />
apt -y install guile-2.2-libs --only-upgrade<br />
<br />
=== Cleaning Up ===<br />
<br />
Remove any extra packages which are no longer needed:<br />
<br />
apt -y autoremove<br />
<br />
Fix up the MySQL and PureFTPd services:<br />
<br />
systemctl disable mysql.service<br />
systemctl enable mysql.service<br />
rm /etc/pure-ftpd/auth/*<br />
ln -s ../conf/ExtAuth /etc/pure-ftpd/auth/60Ext <br />
<br />
Upgrade any web stats to the new format<br />
<br />
find /srv/*/config -maxdepth 1 -mindepth 1 -name 'stats' | sed 's|/config/stats||' | while read path ; do awffull_history_regen --dir "$path/public/htdocs/stats" > "$path/config/.webalizer.hist"; done<br />
<br />
Restart the server to apply the new kernel.<br />
<br />
shutdown -r now<br />
<br />
=== Confirming The Upgrade ===<br />
<br />
Reconnect to the server, and check it's reporting it's running on Debian 11, with a 5.10 Kernel<br />
<br />
lsb_release -a ; uname -a <br />
<br />
List the versions of the sympl packages, each one should start '<code>11.</code>'<br />
<br />
dpkg -l 'sympl-*'<br />
<br />
Run the watchdog, and check it reports no issues.<br />
<br />
sympl-monit<br />
<br />
It should take a few seconds to run but will return immediately with no output if it's already running or load is too high. You should be okay to repeat until you get a result and everything should say 'PASSED'<br />
<br />
Finally, manually check sites look as expected.<br />
<br />
== Upgrading from Debian Stretch ==<br />
<br />
At present we don't have enough data to confirm if a server running [[Debian]] Stretch with Sympl can be safely upgraded to Debian Buster, therefore it's not something we can support at present.<br />
<br />
For this reason, we suggest migrating your configuration to a ''new'' server running a more modern version, rather than upgrading the current one.<br />
<br />
[[Category:Upgrading]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Upgrading_Debian_Versions&diff=497Upgrading Debian Versions2022-09-01T11:09:26Z<p>Kelduum: /* Upgrading from Debian Buster */</p>
<hr />
<div>Upgrading the version of Debian on a server running Sympl can be tricky, as initial dependencies and packages on the server can vary. <br />
<br />
== Upgrading from Debian Buster ==<br />
<br />
Upgrading from Debian Buster to Debian Bullseye is relatively straightforward, but we've only been able to test upgrades on servers with Mythic Beasts, so while this may work with other hosting providers we can't support upgrades with them, as the initial server state may conflict.<br />
<br />
As with any significant upgrade, ensure that any sites or software are compatible with the new versions, and you have full, recent, verified backups.<br />
<br />
The major changes for Sympl in between Debian Buster and Bullseye are:<br />
* PHP7.3 has been updated to PHP7.4, information on the changes are [https://www.php.net/manual/en/migration74.php available on the php.net site].<br />
* Web statistics application Webalizer has been replaced with [https://packages.debian.org/bullseye/awffull AWFFull].<br />
<br />
=== Preparatory Work ===<br />
<br />
First, you should apply any pending updates for the operating system, and Sympl:<br />
<br />
apt -y update && apt -y upgrade && apt -y dist-upgrade && sympl update<br />
<br />
Next, replace the current Sympl sources.list file with one for buster (if you didn't use the Sympl installer or installed it manually, your filenames may vary):<br />
<br />
sed 's|buster|bullseye|g' /etc/apt/sources.list.d/sympl_buster.list > /etc/apt/sources.list.d/sympl_bullseye.list && rm /etc/apt/sources.list.d/sympl_buster.list<br />
<br />
Move the existing distribution sources.list out of the way.<br />
<br />
mv /etc/apt/sources.list /etc/apt/sources.list_buster_$( date +%s )<br />
<br />
Then create a new distribution sources.list with the new distribution codename.<br />
<br />
<nowiki>echo "deb http://mirror.mythic-beasts.com/debian/ bullseye main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bullseye main<br />
<br />
deb http://security.debian.org/debian-security bullseye-security main<br />
deb-src http://security.debian.org/debian-security bullseye-security main<br />
<br />
deb http://mirror.mythic-beasts.com/debian/ bullseye-updates main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bullseye-updates main" > /etc/apt/sources.list</nowiki><br />
<br />
Update the apt data.<br />
<br />
apt update<br />
<br />
Verify there will be enough disk space for the upgrades.<br />
<br />
apt -o APT::Get::Trivial-Only=true full-upgrade<br />
<br />
At this point, if apt mentions theres not going to be enough disk space, then you need to clear some space.<br />
<br />
=== Upgrading ===<br />
<br />
Beyond this point, services will be disrupted, and you should expect around 30 minutes downtime.<br />
<br />
Upgrade any packages which don't have new dependencies. When prompted, answer 'yes' to restart services without asking.<br />
<br />
apt -y upgrade --without-new-pkgs<br />
<br />
Update the rest of the packages, including installing new ones. When prompted, answer 'yes' to upgrade the Roundcube database, and 'keep' the modified roundcube configuration file.<br />
<br />
apt -y full-upgrade<br />
<br />
Update a missing dependency:<br />
<br />
apt -y install guile-2.2-libs --only-upgrade<br />
<br />
=== Cleaning Up ===<br />
<br />
Remove any extra packages which are no longer needed:<br />
<br />
apt -y autoremove<br />
<br />
Fix up the MySQL and PureFTPd services:<br />
<br />
systemctl disable mysql.service<br />
systemctl enable mysql.service<br />
rm /etc/pure-ftpd/auth/*<br />
ln -s ../conf/ExtAuth /etc/pure-ftpd/auth/60Ext <br />
<br />
Upgrade any web stats to the new format<br />
<br />
find /srv/*/config -maxdepth 1 -mindepth 1 -name 'stats' | sed 's|/config/stats||' | while read path ; do awffull_history_regen --dir "$path/public/htdocs/stats" > "$path/config/.webalizer.hist"; done<br />
<br />
Restart the server to apply the new kernel.<br />
<br />
shutdown -r now<br />
<br />
=== Confirming The Upgrade ===<br />
<br />
Reconnect to the server, and check it's reporting it's running on Debian 11, with a 5.10 Kernel<br />
<br />
lsb_release -a ; uname -a <br />
<br />
List the versions of the sympl packages, each one should start '<code>11.</code>'<br />
<br />
dpkg -l 'sympl-*'<br />
<br />
Run the watchdog, and check it reports no issues.<br />
<br />
sympl-monit<br />
<br />
It should take a few seconds to run but will return immediately with no output if it's already running or load is too high. You should be okay to repeat until you get a result and everything should say 'PASSED'<br />
<br />
Finally, manually check sites look as expected.<br />
<br />
== Upgrading from Debian Stretch ==<br />
<br />
At present we don't have enough data to confirm if a server running [[Debian]] Stretch with Sympl can be safely upgraded to Debian Buster, therefore it's not something we can support at present.<br />
<br />
For this reason, we suggest migrating your configuration to a ''new'' server running a more modern version, rather than upgrading the current one.<br />
<br />
[[Category:Upgrading]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Upgrading_Debian_Versions&diff=496Upgrading Debian Versions2022-09-01T11:08:14Z<p>Kelduum: /* Upgrading from Debian Buster */</p>
<hr />
<div>Upgrading the version of Debian on a server running Sympl can be tricky, as initial dependencies and packages on the server can vary. <br />
<br />
== Upgrading from Debian Buster ==<br />
<br />
Upgrading from Debian Buster to Debian Bullseye is relatively straightforward, but we've only been able to test upgrades on servers with Mythic Beasts, so while this may work with other hosting providers we can't support upgrades with them, as the initial server state may conflict.<br />
<br />
As with any significant upgrade, ensure that any sites or software are compatible with the new versions, and you have full, recent, verified backups.<br />
<br />
The major changes for Sympl in between Debian Buster and Bullseye are:<br />
* PHP7.3 has been updated to PHP7.4, information on the changes are [https://www.php.net/manual/en/migration74.php available on the php.net site].<br />
* Web statistics application Webalizer has been replaced with [https://packages.debian.org/bullseye/awffull AWFFull].<br />
<br />
=== Preparatory Work ===<br />
<br />
First, you should apply any pending updates for the operating system, and Sympl:<br />
<br />
apt -y update && apt -y upgrade && apt -y dist-upgrade && sympl update<br />
<br />
Next, replace the current Sympl sources.list file with one for buster (if you didn't use the Sympl installer or installed it manually, your filenames may vary):<br />
<br />
sed 's|buster|bullseye|g' /etc/apt/sources.list.d/sympl_buster.list > /etc/apt/sources.list.d/sympl_bullseye.list && rm /etc/apt/sources.list.d/sympl_buster.list<br />
<br />
Move the existing distribution sources.list out of the way.<br />
<br />
mv /etc/apt/sources.list /etc/apt/sources.list_buster_$( date +%s )<br />
<br />
Then create a new distribution sources.list with the new distribution codename.<br />
<br />
echo "deb http://mirror.mythic-beasts.com/debian/ bullseye main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bullseye main<br />
<br />
deb http://security.debian.org/debian-security bullseye-security main<br />
deb-src http://security.debian.org/debian-security bullseye-security main<br />
<br />
deb http://mirror.mythic-beasts.com/debian/ bullseye-updates main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bullseye-updates main" > /etc/apt/sources.list<br />
<br />
Update the apt data.<br />
<br />
apt update<br />
<br />
Verify there will be enough disk space for the upgrades.<br />
<br />
apt -o APT::Get::Trivial-Only=true full-upgrade<br />
<br />
At this point, if apt mentions theres not going to be enough disk space, then you need to clear some space.<br />
<br />
=== Upgrading ===<br />
<br />
Beyond this point, services will be disrupted, and you should expect around 30 minutes downtime.<br />
<br />
Upgrade any packages which don't have new dependencies. When prompted, answer 'yes' to restart services without asking.<br />
<br />
apt -y upgrade --without-new-pkgs<br />
<br />
Update the rest of the packages, including installing new ones. When prompted, answer 'yes' to upgrade the Roundcube database, and 'keep' the modified roundcube configuration file.<br />
<br />
apt -y full-upgrade<br />
<br />
Update a missing dependency:<br />
<br />
apt -y install guile-2.2-libs --only-upgrade<br />
<br />
=== Cleaning Up ===<br />
<br />
Remove any extra packages which are no longer needed:<br />
<br />
apt -y autoremove<br />
<br />
Fix up the MySQL and PureFTPd services:<br />
<br />
systemctl disable mysql.service<br />
systemctl enable mysql.service<br />
rm /etc/pure-ftpd/auth/*<br />
ln -s ../conf/ExtAuth /etc/pure-ftpd/auth/60Ext <br />
<br />
Upgrade any web stats to the new format<br />
<br />
find /srv/*/config -maxdepth 1 -mindepth 1 -name 'stats' | sed 's|/config/stats||' | while read path ; do awffull_history_regen --dir "$path/public/htdocs/stats" > "$path/config/.webalizer.hist"; done<br />
<br />
Restart the server to apply the new kernel.<br />
<br />
shutdown -r now<br />
<br />
=== Confirming The Upgrade ===<br />
<br />
Reconnect to the server, and check it's reporting it's running on Debian 11, with a 5.10 Kernel<br />
<br />
lsb_release -a ; uname -a <br />
<br />
List the versions of the sympl packages, each one should start '<code>11.</code>'<br />
<br />
dpkg -l 'sympl-*'<br />
<br />
Run the watchdog, and check it reports no issues.<br />
<br />
sympl-monit<br />
<br />
It should take a few seconds to run but will return immediately with no output if it's already running or load is too high. You should be okay to repeat until you get a result and everything should say 'PASSED'<br />
<br />
Finally, manually check sites look as expected.<br />
<br />
== Upgrading from Debian Stretch ==<br />
<br />
At present we don't have enough data to confirm if a server running [[Debian]] Stretch with Sympl can be safely upgraded to Debian Buster, therefore it's not something we can support at present.<br />
<br />
For this reason, we suggest migrating your configuration to a ''new'' server running a more modern version, rather than upgrading the current one.<br />
<br />
[[Category:Upgrading]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Upgrading_Debian&diff=495Upgrading Debian2022-09-01T11:07:31Z<p>Kelduum: Kelduum moved page Upgrading Debian to Upgrading Debian Versions</p>
<hr />
<div>#REDIRECT [[Upgrading Debian Versions]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Upgrading_Debian_Versions&diff=494Upgrading Debian Versions2022-09-01T11:07:31Z<p>Kelduum: Kelduum moved page Upgrading Debian to Upgrading Debian Versions</p>
<hr />
<div>Upgrading the version of Debian on a server running Sympl can be tricky, as initial dependencies and packages on the server can vary. <br />
<br />
== Upgrading from Debian Buster ==<br />
<br />
Upgrading from Debian Buster to Debian Bullseye is relatively straightforward, but we've only been able to test upgrades on servers with Mythic Beasts, so while this may work with other hosting providers we can't support upgrades with them, as the initial server state may conflict.<br />
<br />
As with any significant upgrade, ensure that any sites or software are compatible with the new versions, and you have full, recent, verified backups.<br />
<br />
The major changes for Sympl in between Debian Buster and Bullseye are:<br />
* PHP7.3 has been updated to PHP7.4, information on the changes are [https://www.php.net/manual/en/migration74.php available on the php.net site].<br />
* Web statistics application Webalizer has been replaced with [https://packages.debian.org/bullseye/awffull AWFFull].<br />
<br />
=== Preparatory Work ===<br />
<br />
First, you should apply any pending updates for the operating system, and Sympl:<br />
<br />
apt -y update && apt -y upgrade && apt -y dist-upgrade && sympl update<br />
<br />
Next, replace the current Sympl sources.list file with one for buster (if you didn't use the Sympl installer or installed it manually, your filenames may vary):<br />
<br />
sed 's|buster|bullseye|g' /etc/apt/sources.list.d/sympl_buster.list > /etc/apt/sources.list.d/sympl_bullseye.list && rm /etc/apt/sources.list.d/sympl_buster.list<br />
<br />
Move the existing distribution sources.list out of the way.<br />
<br />
mv /etc/apt/sources.list /etc/apt/sources.list_buster_$( date +%s )<br />
<br />
Then create a new distribution sources.list with the new distribution codename.<br />
<br />
echo "deb http://mirror.mythic-beasts.com/debian/ bullseye main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bullseye main<br />
<br />
deb http://security.debian.org/debian-security bullseye-security main<br />
deb-src http://security.debian.org/debian-security bullseye-security main<br />
<br />
deb http://mirror.mythic-beasts.com/debian/ bullseye-updates main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bullseye-updates main" > /etc/apt/sources.list<br />
<br />
Update the apt data.<br />
<br />
apt update<br />
<br />
Verify there will be enough disk space for the upgrades.<br />
<br />
apt -o APT::Get::Trivial-Only=true full-upgrade<br />
<br />
At this point, if apt mentions theres not going to be enough disk space, then you need to clear some space.<br />
<br />
=== Upgrading ===<br />
<br />
Beyond this point, services will be disrupted, and you should expect around 30 minutes downtime.<br />
<br />
Upgrade any packages which don't have new dependencies. When prompted, answer 'yes' to restart services without asking.<br />
<br />
apt -y upgrade --without-new-pkgs<br />
<br />
Update the rest of the packages, including installing new ones. When prompted, answer 'yes' to upgrade the Roundcube database, and 'keep' the modified roundcube configuration file.<br />
<br />
apt -y full-upgrade<br />
<br />
Update a missing dependency:<br />
<br />
apt -y install guile-2.2-libs --only-upgrade<br />
<br />
=== Cleaning Up ===<br />
<br />
Remove any extra packages which are no longer needed:<br />
<br />
apt -y autoremove<br />
<br />
Fix up the MySQL and PureFTPd services:<br />
<br />
systemctl disable mysql.service<br />
systemctl enable mysql.service<br />
rm /etc/pure-ftpd/auth/*<br />
ln -s ../conf/ExtAuth /etc/pure-ftpd/auth/60Ext <br />
<br />
Upgrade any web stats to the new format<br />
<br />
find /srv/*/config -maxdepth 1 -mindepth 1 -name 'stats' | sed 's|/config/stats||' | while read path ; do awffull_history_regen --dir "$path/public/htdocs/stats" > "$path/config/.webalizer.hist"; done<br />
<br />
Restart the server to apply the new kernel.<br />
<br />
shutdown -r now<br />
<br />
=== Confirming The Upgrade ===<br />
<br />
Reconnect to the server, and check it's reporting it's running on Debian 11, with a 5.10 Kernel<br />
<br />
lsb_release -a ; uname -a <br />
<br />
List the versions of the sympl packages, each one should start '<code>11.</code>'<br />
<br />
dpkg -l 'sympl-*'<br />
<br />
Run the watchdog, and check it reports no issues.<br />
<br />
sympl-monit<br />
<br />
It should take a few seconds to run but will return immediately with no output if it's already running or load is too high. You should be okay to repeat until you get a result and everything should say 'PASSED'<br />
<br />
Finally, manually check sites look as expected.<br />
<br />
<br />
== Upgrading from Debian Stretch ==<br />
<br />
At present we don't have enough data to confirm if a server running [[Debian]] Stretch with Sympl can be safely upgraded to Debian Buster, therefore it's not something we can support at present.<br />
<br />
For this reason, we suggest migrating your configuration to a ''new'' server running a more modern version, rather than upgrading the current one.<br />
<br />
[[Category:Upgrading]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Upgrading_Debian_Versions&diff=493Upgrading Debian Versions2022-09-01T11:07:03Z<p>Kelduum: </p>
<hr />
<div>Upgrading the version of Debian on a server running Sympl can be tricky, as initial dependencies and packages on the server can vary. <br />
<br />
== Upgrading from Debian Buster ==<br />
<br />
Upgrading from Debian Buster to Debian Bullseye is relatively straightforward, but we've only been able to test upgrades on servers with Mythic Beasts, so while this may work with other hosting providers we can't support upgrades with them, as the initial server state may conflict.<br />
<br />
As with any significant upgrade, ensure that any sites or software are compatible with the new versions, and you have full, recent, verified backups.<br />
<br />
The major changes for Sympl in between Debian Buster and Bullseye are:<br />
* PHP7.3 has been updated to PHP7.4, information on the changes are [https://www.php.net/manual/en/migration74.php available on the php.net site].<br />
* Web statistics application Webalizer has been replaced with [https://packages.debian.org/bullseye/awffull AWFFull].<br />
<br />
=== Preparatory Work ===<br />
<br />
First, you should apply any pending updates for the operating system, and Sympl:<br />
<br />
apt -y update && apt -y upgrade && apt -y dist-upgrade && sympl update<br />
<br />
Next, replace the current Sympl sources.list file with one for buster (if you didn't use the Sympl installer or installed it manually, your filenames may vary):<br />
<br />
sed 's|buster|bullseye|g' /etc/apt/sources.list.d/sympl_buster.list > /etc/apt/sources.list.d/sympl_bullseye.list && rm /etc/apt/sources.list.d/sympl_buster.list<br />
<br />
Move the existing distribution sources.list out of the way.<br />
<br />
mv /etc/apt/sources.list /etc/apt/sources.list_buster_$( date +%s )<br />
<br />
Then create a new distribution sources.list with the new distribution codename.<br />
<br />
echo "deb http://mirror.mythic-beasts.com/debian/ bullseye main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bullseye main<br />
<br />
deb http://security.debian.org/debian-security bullseye-security main<br />
deb-src http://security.debian.org/debian-security bullseye-security main<br />
<br />
deb http://mirror.mythic-beasts.com/debian/ bullseye-updates main<br />
deb-src http://mirror.mythic-beasts.com/debian/ bullseye-updates main" > /etc/apt/sources.list<br />
<br />
Update the apt data.<br />
<br />
apt update<br />
<br />
Verify there will be enough disk space for the upgrades.<br />
<br />
apt -o APT::Get::Trivial-Only=true full-upgrade<br />
<br />
At this point, if apt mentions theres not going to be enough disk space, then you need to clear some space.<br />
<br />
=== Upgrading ===<br />
<br />
Beyond this point, services will be disrupted, and you should expect around 30 minutes downtime.<br />
<br />
Upgrade any packages which don't have new dependencies. When prompted, answer 'yes' to restart services without asking.<br />
<br />
apt -y upgrade --without-new-pkgs<br />
<br />
Update the rest of the packages, including installing new ones. When prompted, answer 'yes' to upgrade the Roundcube database, and 'keep' the modified roundcube configuration file.<br />
<br />
apt -y full-upgrade<br />
<br />
Update a missing dependency:<br />
<br />
apt -y install guile-2.2-libs --only-upgrade<br />
<br />
=== Cleaning Up ===<br />
<br />
Remove any extra packages which are no longer needed:<br />
<br />
apt -y autoremove<br />
<br />
Fix up the MySQL and PureFTPd services:<br />
<br />
systemctl disable mysql.service<br />
systemctl enable mysql.service<br />
rm /etc/pure-ftpd/auth/*<br />
ln -s ../conf/ExtAuth /etc/pure-ftpd/auth/60Ext <br />
<br />
Upgrade any web stats to the new format<br />
<br />
find /srv/*/config -maxdepth 1 -mindepth 1 -name 'stats' | sed 's|/config/stats||' | while read path ; do awffull_history_regen --dir "$path/public/htdocs/stats" > "$path/config/.webalizer.hist"; done<br />
<br />
Restart the server to apply the new kernel.<br />
<br />
shutdown -r now<br />
<br />
=== Confirming The Upgrade ===<br />
<br />
Reconnect to the server, and check it's reporting it's running on Debian 11, with a 5.10 Kernel<br />
<br />
lsb_release -a ; uname -a <br />
<br />
List the versions of the sympl packages, each one should start '<code>11.</code>'<br />
<br />
dpkg -l 'sympl-*'<br />
<br />
Run the watchdog, and check it reports no issues.<br />
<br />
sympl-monit<br />
<br />
It should take a few seconds to run but will return immediately with no output if it's already running or load is too high. You should be okay to repeat until you get a result and everything should say 'PASSED'<br />
<br />
Finally, manually check sites look as expected.<br />
<br />
<br />
== Upgrading from Debian Stretch ==<br />
<br />
At present we don't have enough data to confirm if a server running [[Debian]] Stretch with Sympl can be safely upgraded to Debian Buster, therefore it's not something we can support at present.<br />
<br />
For this reason, we suggest migrating your configuration to a ''new'' server running a more modern version, rather than upgrading the current one.<br />
<br />
[[Category:Upgrading]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=Firewall_Configuration_Reference&diff=484Firewall Configuration Reference2022-07-26T13:48:38Z<p>Kelduum: /* Blacklisting */</p>
<hr />
<div>Sympl contains an easy to use firewall system based on [[iptables]] which protects the server by controlling inbound and outbound connections, comprised of a set of rules as well as automatic whitelist and blacklist configuration.<br />
<br />
Configuration changes can be made via SSH or serial/VNC console as the <code>sympl</code> user, and will take effect immediately.<br />
<br />
==Basic Firewall Configuration==<br />
<blockquote>The default configuration for Sympl should cover the majority of use cases, and caution should be taken when making any changes in case you lock yourself out. If this happens, you can still access the server via the serial or VNC console.</blockquote>The configuration of the sympl-firewall package is built from a series of files and directories in the <code>/etc/sympl/firewall/</code> directory, with incoming connections controlled by the files in <code>/etc/sympl/firewall/incoming.d/</code> and the outgoing connections controlled by the files in <code>/etc/sympl/firewall/outgoing.d/</code> (which does not filter outgoing traffic by default).<br />
<br />
These files are in the format of <code>'''''index_number'''''-'''''service_name_or_number'''''</code> with the <code>'''''index_number'''''</code> controlling order of the rules, and the <code>'''''service_name_or_number'''''</code> as either a service name taken from <code>/etc/services</code>, a TCP/UDP port number, or one of a few special keywords.<br />
<br />
Each of these files can either be empty, or contain a list of hostnames or IP addresses which the rule applies to, one per line.<blockquote>If hostnames are used in the configuration files rather than IP addresses, they will be translated when the firewall is updated, and the result cached for up to 15 minutes. If the DNS result changes in this period then the result will not update, therefore IP addresses should be used where possible.</blockquote><br />
<br />
==Firewall Keywords==<br />
Sympl uses a number of specific keywords for a number of non port-related rules, in the <code>incoming.d/</code> and <code>outgoing.d/</code> directories.<br />
<br />
As with normal service name rules, these can contain a target IP address or hostname, one per line which the rule will apply to.<br />
{| class="wikitable sortable"<br />
|+<br />
!Keyword<br />
!Action<br />
|-<br />
|<code>accept</code><br />
|Accepts all connections. Uses the [[iptables]] <code>ACCEPT</code> target.<br />
|-<br />
|<code>allow</code><br />
|Alias of <code>accept</code>.<br />
|-<br />
|<code>whitelist</code><br />
|Alias of <code>accept</code>.<br />
|-<br />
| colspan="2" |<br />
|-<br />
|<code>new</code><br />
|Permit new connections. Uses the iptables <code>NEW</code> target.<br />
|-<br />
|<code>established</code><br />
|Permit traffic from connections which are already established. Uses the [[iptables]] <code>ESTABLISHED</code> target.<br />
|-<br />
|<code>related</code><br />
|Accept new connections associated with existing connections, such as DNS queries and FTP transfers. Uses the iptables <code>RELATED</code> target.<br />
|-<br />
| colspan="2" |<br />
|-<br />
|<code>reject</code><br />
|Reject all connections. Uses the [[iptables]] <code>REJECT</code> target. Returns a 'TCP reset' or 'port unreachable' message.<br />
|-<br />
|<code>blacklist</code><br />
|Alias of <code>reject</code>.<br />
|-<br />
| colspan="2" |<br />
|-<br />
|<code>drop</code><br />
|Drops all traffic. Uses the [[iptables]] <code>DROP</code> target.<br />
|-<br />
| colspan="2" |<br />
|-<br />
|<code>ping</code><br />
|Permits ICMP echo-request, echo-reply and ttl-exceeded traffic, which allows the server to respond to pings and show up on traceroute tests.<br />
|-<br />
|<code>icmp</code><br />
|Permit all ICMP traffic. Applies to IPv4 only.<br />
|-<br />
|<code>icmpv6</code><br />
|Permit all ICMP6 traffic. Applies to IPv6 only.<br />
|-<br />
|<code>essential-icmpv6</code><br />
|Accept required ICMP traffic for IPv6 to operate. Allows destination-unreachable, packet-too-big, parameter-problem, router-solicitation, router-advertisement, neighbour-solicitation and neighbour-advertisement traffic.<br />
If this rule is removed IPv6 will very likely cease working properly. Applies to IPv6 only.<br />
|-<br />
| colspan="2" |<br />
|-<br />
|<code>dns</code><br />
|Accept TCP and UDP connections from port 53 to high-numbered unprivileged ports. Designed to allow replies to DNS queries, but may be removed in favour of <code>related</code>. Applies to incoming connections only.<br />
|-<br />
|<code>ftp</code><br />
|Permit connections on both port 20 (ftp-data) and 21 (ftp-control).<br />
|-<br />
|<code>collector</code><br />
|Permit TCP connections on port 1919.<br />
|-<br />
|<code>imager</code><br />
|Permit TCP connections on port 5000.<br />
|}<br />
Detailed definitions for these rules are contained in <code>/usr/share/sympl/firewall/rule.d/</code>, and new rules can be created in <code>/usr/local/sympl/symbiosis/firewall/rule.d/</code> if desired.<br />
<br />
===Firewall Example===<br />
Here is an example of a basic firewall configuration for incoming traffic in Sympl. The files below all reside in /etc/sympl/firewall/incoming.d/<br />
{| class="wikitable"<br />
|+<br />
!File<br />
!Containing<br />
!Result<br />
|-<br />
|<code>00-established</code><br />
|''empty''<br />
|Accepts packets from any already established connections.<br />
|-<br />
|<code>00-related</code><br />
|''empty''<br />
|Accepts packets from sources related to any already established traffic.<br />
|-<br />
|<code>05-essential-icmpv6</code><br />
|''empty''<br />
|Allows the required [[ICMP]] traffic for IPv6 to function.<br />
|-<br />
|<code>05-ping</code><br />
|<br />
''10.11.12.13''<br />
|Allows ICMP ping traffic, but only from the IPv4 address <code>10.11.12.13</code>. IPv6 traffic is not allowed by this rule.<br />
|-<br />
|<code>07-ssh</code><br />
|<br />
10.11.12.13<br />
2001:0db8:85a3::/64<br />
|Allows connections to port 22 (SSH) from IPv4 addresses between 10.11.12.13, and IPv6 traffic from the range 2001:0db8:85a3::/64<br />
|-<br />
|<code>10-http</code><br />
|''empty''<br />
|Allows traffic to port 80 (HTTP).<br />
|-<br />
|<code>10-https</code><br />
|''empty''<br />
|Allows traffic to port 443 (HTTPS).<br />
|-<br />
|<code>100-pop3</code><br />
|''empty''<br />
|Allows traffic to port 110 (POP3). Note that this is processed at this point as the numbers are sorted as text.<br />
|-<br />
|<code>20-25</code><br />
|<br />
''172.16.17.0/24''<br />
|Allows connections to port 25 (SMTP) from the <code>172.16.17.0/24</code> range only.<br />
|-<br />
|<code>99-reject</code><br />
|''empty''<br />
|Rejects any other traffic.<br />
|}<br />
You can view the generated ''incoming'' firewall rules being used by [[iptables]] with <code>sudo iptables -L INPUT -vn</code>, which for the above looks like this:<br />
Chain INPUT (policy ACCEPT 0 packets, 0 bytes)<br />
pkts bytes target prot opt in out source destination<br />
0 0 ACCEPT all -- lo * 0.0.0.0/0 0.0.0.0/0<br />
16 1024 whitelist all -- * * 0.0.0.0/0 0.0.0.0/0<br />
0 0 blacklist all -- * * 0.0.0.0/0 0.0.0.0/0<br />
0 0 ACCEPT all -- * * 0.0.0.0/0 0.0.0.0/0 state ESTABLISHED<br />
0 0 ACCEPT all -- * * 0.0.0.0/0 0.0.0.0/0 state RELATED<br />
0 0 ACCEPT icmp -- * * 10.11.12.13 0.0.0.0/0 icmp type 8<br />
0 0 ACCEPT icmp -- * * 10.11.12.13 0.0.0.0/0 icmp type 0<br />
0 0 ACCEPT icmp -- * * 10.11.12.13 0.0.0.0/0 icmp type 11<br />
0 0 ACCEPT tcp -- * * 10.11.12.13 0.0.0.0/0 tcp dpt:22<br />
0 0 ACCEPT udp -- * * 10.11.12.13 0.0.0.0/0 udp dpt:22<br />
0 0 ACCEPT tcp -- * * 0.0.0.0/0 0.0.0.0/0 tcp dpt:80<br />
0 0 ACCEPT udp -- * * 0.0.0.0/0 0.0.0.0/0 udp dpt:80<br />
0 0 ACCEPT tcp -- * * 0.0.0.0/0 0.0.0.0/0 tcp dpt:443<br />
0 0 ACCEPT udp -- * * 0.0.0.0/0 0.0.0.0/0 udp dpt:443<br />
0 0 ACCEPT tcp -- * * 0.0.0.0/0 0.0.0.0/0 tcp dpt:110<br />
0 0 ACCEPT udp -- * * 0.0.0.0/0 0.0.0.0/0 udp dpt:110<br />
0 0 ACCEPT tcp -- * * 172.16.17.0/24 0.0.0.0/0 tcp dpt:25<br />
0 0 ACCEPT udp -- * * 172.16.17.0/24 0.0.0.0/0 udp dpt:25<br />
0 0 REJECT all -- * * 0.0.0.0/0 0.0.0.0/0 reject-with icmp-port-unreachable<br />
<blockquote>Note in the above result, the IPv6 address is not listed. This uses the alternate <code>ip6tables</code> tool to list it's rules.</blockquote><br />
<br />
==Custom Firewall Additions==<br />
While the Sympl firewall configuration should cover most day-to-day firewall administration, sometimes custom changes are needed which are more complex, such as when the server is running something like [[Docker]] which configures the firewall itself.<br />
<br />
In these instances, scripts can be placed in <code>/etc/sympl/firewall/local.d/</code> which are run once the any firewall rules have been loaded, and can be used to adjust firewall rules using [[iptables]] and/or [[ip6tables]].<br />
<br />
These scripts must be named in [https://manpages.debian.org/buster/debianutils/run-parts.8.en.html run-parts] format, with the script marked executable and the filename being limited to alphanumeric characters. All scripts in <code>firewall/local.d/</code> must exit with a zero status normally, as any other result will be considered a failure, and will revert any changes.<br />
<br />
==Blocking and Allowing Hosts and Networks==<br />
Sympl includes both support for automatically blacklisting abusive hosts with a blacklist, and allowing known-good hosts with a whitelist.<br />
<br />
===Blacklisting===<br />
The <code>sympl-firewall-blacklist</code> task run every 15 minutes, and scans the servers log files for abusive behavior from malicious hosts on the internet, which will lead to the hosts being blocked for 2 days.<br />
<br />
Malicious activity is defined as 25 failed logins to:<br />
<br />
*SSH<br />
*FTP<br />
*SMTP<br />
*POP3/IMAP/Sieve<br />
<br />
The definitions of abusive behaviour are stored in <code>/etc/sympl/firewall/patterns.d/</code>, and contain filename, ports to block, and patterns to match against, with the tag <code>__IP__</code> being the source of the abuse.<blockquote>Any IPv6 addresses automatically matched result in the relevant /112 network being blocked, as this is the smallest assignment of addresses recommended.</blockquote>Automatically blocked IP addresses will have names ending <code>.auto</code> and are blocked for 2 days, however manual block rules can be added to the blacklist by creating a file in <code>/etc/sympl/firewall/blacklist.d/</code> named after the IP address, for example <code>/etc/sympl/firewall/blacklist.d/10.11.12.13</code>.<br />
<br />
To block an IP range, create a file with the range in [[CIDR Notation|CIDR notation]], with the slash (<code>/</code>) character replaced with a pipe character (<code>|</code>).<br />
<br />
For example, to block the IP range <code>172.31.65.0/24</code>, you would run <code>touch '/etc/sympl/firewall/blacklist.d/172.31.65.0|24'</code>, using the quotes to allow usage of the normally special pipe character.<br />
<br />
Files can be blank or contain the text <code>all</code> which will block all traffic, or be a list of ports to allow, one per line.<br />
<br />
To fully disable the blacklisting for both automatic and manual entries, create the file <code>/etc/sympl/firewall/blacklist.d/disabled</code>.<br />
<br />
===Whitelisting===<br />
Similar to the blacklist, the <code>sympl-firewall-whitelist</code> task runs once per hour, and checks for IPs which successfully connected via [[SSH]] or [[SFTP]], and automatically allows access to SSH for 7 days, even if the IP address becomes blacklisted for other reasons.<br />
<br />
The whitelist ''only'' has one item to match, the IP addresses from <code>/var/log/wtmp</code>, and whitelists the successful IP address for both IPv4 and IPv6, naming the files after the IP address.<br />
<br />
To add manual rules, add them in the same format as the blacklist, in <code>/etc/sympl/firewall/whitelist.d/</code>.<br />
<br />
To fully disable the blacklisting for both automatic and manual entries, create the file <code>/etc/sympl/firewall/whitelist.d/disabled</code>.<br />
<br />
==SYN Flood Protection==<br />
Sympl includes some basic [[SYN flood]] protection, which attempts to open a all available ports on the server, consuming resources until the server is unable to server any content.<br />
<br />
This can be enabled by creating the file <code>/etc/sympl/firewall/incoming.d/00-syn-ack-flood-protection</code>.<br />
<br />
==Disabling the Firewall==<br />
To prevent firewall updates, create the file . This will disable updates, but not clear the firewall rules.<br />
<br />
To clear all firewall rules, and allow all hosts to access all publicly visible services (not recommended!), run <code>sudo sympl-firewall flush</code>.<br />
<br />
==Configuration Reference==<br />
<section begin=config /><br />
{| class="wikitable sortable"<br />
!File or Directory<br />
!Used For<br />
!More<br />
|-<br />
|<code>/etc/sympl/firewall/</code><br />
|Contains the firewall configuration.<br />
|<small>[[Firewall Configuration Reference#Basic Firewall Configuration|More...]]</small><br />
|-<br />
|<code>/etc/sympl/firewall/incoming.d/</code><br />
|Contains rules for incoming traffic.<br />
|<small>[[Firewall Configuration Reference#Basic Firewall Configuration|More...]]</small><br />
|-<br />
|<code>/etc/sympl/firewall/outgoing.d/</code><br />
|Contains rules for outgoing traffic.<br />
|<small>[[Firewall Configuration Reference#Basic Firewall Configuration|More...]]</small><br />
|-<br />
|<code>/etc/sympl/firewall/disabled</code><br />
|Disables all updates for <code>sympl-firewall</code>.<br />
|<small>[[Firewall Configuration Reference#Disabling the Firewall|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>/etc/sympl/firewall/blacklist.d/</code><br />
|Contains automatic and manual blacklist rules.<br />
|<small>[[Firewall Configuration Reference#Blacklisting|More...]]</small><br />
|-<br />
|<code>/etc/sympl/firewall/blacklist.d/disabled</code><br />
|Fully disables the automatic blacklist functionality.<br />
|<small>[[Firewall Configuration Reference#Blacklisting|More...]]</small><br />
|-<br />
|<code>/etc/sympl/firewall/patterns.d/</code><br />
|Contains patterns matched to detect abusive hosts.<br />
|<small>[[Firewall Configuration Reference#Blacklisting|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>/etc/sympl/firewall/whitelist.d/</code><br />
|Contains automatic and manual whitelist rules.<br />
|<small>[[Firewall Configuration Reference#Whitelisting|More...]]</small><br />
|-<br />
|<code>/etc/sympl/firewall/whitelist.d/disabled</code><br />
|Fully disables the automatic whitelist functionality.<br />
|<small>[[Firewall Configuration Reference#Whitelisting|More...]]</small><br />
|-<br />
| colspan="3" |<br />
|-<br />
|<code>/etc/sympl/firewall/local.d/</code><br />
|Contains manual rules to be run after the firewall is updated.<br />
|<small>[[Firewall Configuration Reference#Custom Firewall Additions|More...]]</small><br />
|}<section end=config /><blockquote>See also [[Configuration_Reference|Configuration Reference]] for other configuration files.</blockquote><br />
[[Category:Reference]]<br />
[[Category:Firewall]]</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=MediaWiki:Sidebar&diff=473MediaWiki:Sidebar2022-06-15T13:15:36Z<p>Kelduum: </p>
<hr />
<div><br />
* navigation<br />
** mainpage|mainpage-description<br />
** recentchanges-url|recentchanges<br />
** randompage-url|randompage<br />
** helppage|help-mediawiki<br />
* Links<br />
** https://sympl.io|sympl.io<br />
** https://forum.sympl.io|Support Forum<br />
** https://bugs.sympl.io|Issue Tracker<br />
* categorytree-portlet<br />
* Wanted Content<br />
** Special:Wantedpages|Wanted Pages<br />
** :Category:Beta_Documentation|Beta Documentation<br />
** :Category:Stub|Stub Pages<br />
** Special:ShortPages|Short Pages<br />
* SEARCH<br />
* TOOLBOX<br />
* LANGUAGES</div>Kelduumhttps://wiki.sympl.io/w/index.php?title=MediaWiki:Sidebar&diff=472MediaWiki:Sidebar2022-06-15T13:05:14Z<p>Kelduum: </p>
<hr />
<div><br />
* navigation<br />
** mainpage|mainpage-description<br />
** recentchanges-url|recentchanges<br />
** randompage-url|randompage<br />
** helppage|help-mediawiki<br />
* Links<br />
** https://sympl.io|sympl.io<br />
** https://forum.sympl.io|Support Forum<br />
** https://bugs.sympl.io|Issue Tracker<br />
* Categories<br />
** :Category:Basic Administration|Documentation<br />
* categorytree-portlet<br />
* Wanted Content<br />
** Special:Wantedpages|Wanted Pages<br />
** :Category:Beta_Documentation|Beta Documentation<br />
** :Category:Stub|Stub Pages<br />
** Special:ShortPages|Short Pages<br />
* SEARCH<br />
* TOOLBOX<br />
* LANGUAGES</div>Kelduum