Every Operating System is a little bit different, even when Virtualmin puts a common UI on top of it. This is a collection of observations about various operating systems, and common pitfalls.
A common cause of installation/update errors on CentOS is due to having third party repositories installed. If the installer is having trouble installing packages, verify that there aren't any third party repositories conflicting with your primary repositories.
Upgrading Debian etch to lenny with distupgrade
Upgrading Debian Lenny to Squeeze with distupgrade
Upgrading Ubuntu 8.04 LTS to 10.04 LTS with distupgrade
On Ubuntu 10.04, "hostname -f" needs to resolve to your full hostname, or the installation may not work correctly.
FreeBSD Username and Group Limits
FreeBSD has much shorter username limits than Linux, by default, and thus it is usually impossible to use the full domain name as the unique suffix for usernames. A full world rebuild is required to work around this issue, in order to insure that the kernel and all support tools agree on the longer username length.
FreeBSD has a limit of 16 secondary groups, and so permissions on homes can never be tighter than 751 (which makes directories list-able by all users that have a shell), because Apache must be able to access the public_html directory. As long as suexec is used for all web applications, files containing sensitive data can, and should, have 750 or tighter permissions. It is not known if a world rebuild with a higher limit is safe or feasible.
pkg_add and ports lack transactional installation capabilities, and thus it is impossible for an automated process like install.sh to insure that packages are all installed successfully, or that a failure is predictable (in the sense that a failed install results in nothing rather than the appearance of an installation). Compounding this issue, pkg_add currently has at least two bugs. The first bug leads to occasional "fatal" errors being reported, even when the package was successfully installed. The second is merely a segmentation fault, apparently triggered by a race condition, which is intermittent and difficult to reproduce. Thus, it is not only likely that problems may occur during installation, install.sh cannot accurately detect it when they do. So, install.sh may complete without error on FreeBSD, even if the installation of some or all packages failed. There is no good workaround for this problem, aside from fixing the failed package installations manually once they are identified. The virtualmin-install.log usually provides the clues you need to correct these problems.
Plan for some down time (sorry, it's gotta happen with a distribution upgrade, regardless of Virtualmin being involved).
Convert your apt Virtualmin source to point to the virtualmin-lenny repo, instead of virtualmin-etch. Also add a virtualmin-universal source (this is new for lenny and will make upgrades and some other stuff easier/faster in the future; both on my side as the maintainer of the repos and on your side as the user). The virtualmin-universal source line looks like:
deb http://SERIAL:KEY@software.virtualmin.com/debian/ virtualmin-universal
Or, if using Virtualmin GPL:
deb http://software.virtualmin.com/gpl/debian/ virtualmin-universal
apt-get install apache2
apt-get install virtualmin-base
This will probably (hopefully) install apache2-suexec-custom. Configure it in /etc/apache2/suexec/www-data to point to /home instead of /var/www (this is the first line in the file).
Assuming upgrading virtualmin-base worked, you can then probably safely dist-upgrade. Let us know about any weird dependency issues that seem Virtualmin related by filing a ticket in the issue tracker.
Note: Before upgrading, please beware that PHP 5.3, provided with Ubuntu 10.04, is not supported by several of the Virtualmin Professional Install Scripts. Since we have no control over those applications, the timeline for when they will work with PHP 5.3 is not under out control. We strongly recommend you check all of the applications you use, to be sure they will survive the upgrade, before moving from 8.04 to 10.04.
Plan for some down time (sorry, it's gotta happen with a distribution upgrade, regardless of Virtualmin being involved).
Convert your apt Virtualmin source in /etc/apt/sources.list to point to the virtualmin-lucid repo, instead of virtualmin-hardy. Also add a virtualmin-universal source (this is new for lenny and will make upgrades and some other stuff easier/faster in the future; both on my side as the maintainer of the repos and on your side as the user). The virtualmin-universal source line looks like:
deb http://SERIAL:KEY@software.virtualmin.com/ubuntu/ virtualmin-universal
Or, if using Virtualmin GPL:
deb http://software.virtualmin.com/gpl/ubuntu/ virtualmin-universal
apt-get install apache2
apt-get install virtualmin-base
This will probably (hopefully) install apache2-suexec-custom. Configure it in /etc/apache2/suexec/www-data to point to /home instead of /var/www (this is the first line in the file).
Assuming upgrading virtualmin-base worked, you can then probably safely dist-upgrade. Let us know about any weird dependency issues that seem Virtualmin related by filing a ticket in the issue tracker.