[[ch-installing-and-upgrading]]
== Installing and administering Symbiosis

Symbiosis will install well on a freshly-installed Debian 8.0 system.
Currently it is only available for _i386_ and _amd64_ architectures,
running on the Linux kernel.

It is designed to be as friendly as possible for beginners, whilst
maintaining flexibility for more experienced systems administrators.
Later in this chapter we'll spell out a few basics to bear in mind
when working with a system running Symbiosis.

[[s-installing-on-jessie]]
=== Installing Symbiosis running on Debian 8.0 (Jessie)
(((Symbiosis, installing)))

Installing on a fresh Jessie system is relatively simple. First, add
the Bytemark package signing key:

----------------
curl -sSL https://secure.bytemark.co.uk/key/repositories-2006.key | sudo apt-key add -
----------------

Second, add the following to +/etc/apt/sources.list.d/symbiosis.list+:

----------------
#
# Bytemark Symbiosis Packages
#
deb	http://symbiosis.bytemark.co.uk/jessie/ ./
deb-src	http://symbiosis.bytemark.co.uk/jessie/ ./
----------------

Once that is in your sources, run:

----------------
apt-get update
apt-get install --install-recommends bytemark-symbiosis
----------------

At the end of this process, you should have a fully functioning 
Symbiosis system with all of the features documented here available 
to you for use. 

=== Installing Symbiosis Jessie using the BigV control panel

Users of Bytemark's BigV system can get a fresh install of Symbiosis by
simply selecting the image at VM install time. The panel is accessed at
https://panel-beta.bytemark.co.uk. Once logged in, using the 'Add virtual machine'
button, a machine can be installed within a few seconds. Select the jessie symbiosis
image as per the screenshot below.

screenshot::figures/bigv-install.png



[[s-upgrading-from-wheezy]]
=== Upgrading Symbiosis running on Debian 7.0 (Wheezy)
(((Symbiosis, upgrading)))

Debian have http://www.debian.org/releases/jessie/releasenotes[comprehensive release
notes], of which chapter 4 covers the recommended upgrade procedure. We have
provided a shorter version for this, which is immediately below:

The first thing to do is make sure that you have backups. These
should be kept in /var/backups/localhost, and they should be up to date.

[NOTE]
Any modifications you may have made to Symbiosis scripts will likely be
lost during the upgrade, so you should be prepared to reapply these
changes after the upgrade.

Next, alter /etc/apt/sources.list.  Change all instances of the word
'wheezy' to 'jessie'. If you have backports, you can remove them, and
any entries for Wheezy LTS should also be removed.  Then change the
Symbiosis repository lines to match those shown in the previous
section.

You can then proceed with the upgrade by running:

----------------
apt-get update
apt-get dist-upgrade
----------------

As this is an upgrade for *all* the software on the system, a large
number of questions may be asked about configuration files during the
upgrade.  Some of these will relate to packages Symbiosis has
installed as dependencies, and the answers to these questions are
given below.

[qanda]
.Questions asked during the upgrade
Configuring d-push: Please choose the web server that should be automatically configured to run d-push. Web server to reconfigure automatically::
    apache2                         
Configuring libc6: Restart services during package upgrades without asking?::
    Yes
Configuration file '/etc/sysctl.conf' modified since installation::
    Install the package maintainer's version.
Cnfiguration file '/etc/dovecot/dovecot.conf' modified since installation::
    Install the package maintainer's version. (*NB* This will be
    replaced by Symbiosis later in the upgrade process, but
    IMAP/POP3/SMTP logins will be broken until that point.)
Configuration file '/etc/crontab' modified since installation::
    Install the package maintainer's version.
Configuration file '/etc/phpmyadmin/config.inc.php'::
    Install the package maintainer's version.
Configuring phpmyadmin: Perform upgrade on database for phpmyadmin with dbconfig-common?::
    Yes (*NB* this requires your *root* MySQL password)
Configuration file '/etc/default/spamassassin' modified since installation::
    Install the package maintainer's version.

That should be everything; you may have been asked other questions if you have
installed extra packages on your system - answer them as you see fit.

[[s-upgrade-to-jessie-release-notes]]
=== Release notes
(((Symbiosis, jessie release)))

This release of Symbiosis includes a number of new features that are
summarised in <<ch-whatsnew>>.

==== Apache HTTPd upgrade from 2.2 to 2.4
(((HTTP, new apache)))

Apache has undergone a major version change in Jessie. If you've made any 
custom Apache config changes, you may need to look at the docs. Apache have
an https://httpd.apache.org/docs/2.4/upgrading.html[upgrade guide] that details
all of the changes and some gotchas.

==== New version of Prosody
(((XMPP, new prosody)))

Prosody has been upgraded from version 0.8 to 0.9. The
http://blog.prosody.im/prosody-0-9-0-released[prosody site has some
more information]


[[s-symbiosis-components]]
=== Packages installed by Symbiosis
(((Symbiosis, components)))

Each component that makes up Symbiosis is separately packaged as
follows.  Each package can be installed individually if needed.

bytemark-symbiosis:: Meta-package that pulls in the core requirements
for a Symbiosis system, and as well as recommending all packages
needed for a complete Symbiosis system.

symbiosis-backup:: Organises and configures backup2l to backup vital
parts of the system, and rsync them to a remote location.

symbiosis-common:: Contains the core libraries that Symbiosis uses to
operate.

symbiosis-dns:: Adds automatic DNS generation and upload to the
system.  Ties in with the Bytemark DNS service.

symbiosis-email:: Configures @Exim@ and @Dovecot@ for use with
Symbiosis.

symbiosis-email-activesync:: - Provides email access using the 
Microsoft Exchange ActiveSync protocol

symbiosis-firewall:: Maintains the @iptables@ and @ip6tables@
firewalls, as well as providing automatic blacklisting and
whitelisting.

symbiosis-ftpd:: Configures @pure-ftpd@ to work with Symbiosis.

symbiosis-httpd:: Configures the @Apache@ web server.

symbiosis-key:: Adds the Bytemark Symbiosis key to @apt@.

symbiosis-monit:: Provides service monitoring.

symbiosis-mysql:: Brings in @MySQL@ version 5.5, and configures it to
bind to all interfaces, not just localhost, for remote access.

symbiosis-pam:: Brings in two PAM dependencies to make the system more
secure -- one checks passwords and warns when they are weak, the other
sets per-user temporary directories.

symbiosis-phpmyadmin:: Brings in @phpMyAdmin@, and configures it to
use HTTP authentication.

symbiosis-webmail:: Adds webmail functionality, using either
Squirrelmail (with Avelsieve) or Roundcube. Now separated into
two packages :

symbiosis-webmail-squirrelmail:: Provide webmail access to Symbiosis using Squirrelmail (the default)

symbiosis-webmail-roundcube:: Provide webmail access to Symbiosis using Roundcube

symbiosis-xmpp:: Adds an XMPP server, which can be used to chat to people on the global XMPP network.

=== Systems administration and Symbiosis
(((Sysadmin)))

Symbiosis is an attempt to encourage best practice at all times in
systems administration, whilst keeping things as simple as possible,
and free of surprises.  As a result there are a few general rules to
bear in mind when tinkering with your system.

==== Use of +root+, and other users
(((root user)))

As far as possible Symbiosis will discourage you from using +root+
when logging in and configuring the system.  This primarily applies to

  * Anything in the [directory]'/srv/' directory
  * The firewall configuration in [directory]'/etc/symbiosis/firewall'

For example, if a directory in [directory]'/srv' is owned by a system
user or group, i.e. one with a UID/GID less than 1000, then it will
not show up to various tasks, including, but not limited to,

  * Email and FTP logins
  * Cron tasks in 'config/crontab'
  * Apache logging to [directory]'public/logs/'
  * Mail delivery to mailboxes.

In short, try not to use +root+ if at all possible.

However it is perfectly possible to configure separate domains in
[directory]'/srv/' to be owned by different users, as long as they are
non-system users, i.e. ones with user IDs greater than 1000.  All
programs will respect these permissions.

==== Customising configurations

Lots of configuration on the system is automatically generated to make
Symbiosis work as it does.  In previous releases of Symbiosis this
meant that files would get overwritten without notice.  However as of
the Squeeze release in February 2012 configuration files are handled
more conservatively.

Two things to watch out for.  If a configuration file has 

--------------------------------------------------
# DO NOT EDIT THIS FILE - CHANGES WILL BE OVERWRITTEN
--------------------------------------------------

written in it, then there is a high chance that any changes will be
overwritten.  It has to be the exact wording and spacing above for
overwriting to take place, so if that sentence is removed from the
configuration then it *will not* get overwritten.

Similarly many files are generated from templates, for example DNS and
apache snippets.  These will now have a checksum at the bottom of the
file.

--------------------------------------------------
# Checksum MD5 586732ff59e60115d0ec1c4905c72773
--------------------------------------------------

This checksum allows Symbiosis scripts to establish if the template
used to generate the snippet has changed, if the data used in the
generation has changed, or if the file itself has been edited.  For
example if an IP address is changed by editing 'config/ip', then that
would allow the apache snippet for that domain can be updated, as can
the DNS snippet.

This also means that sysadmins can edit the templates, and allow them
to regenerate, or edit the snippets themselves safe in the knowledge
that their changes will not get overwritten.

==== Other configuration styles

The Backup2l, Dovecot, and Exim configuration files are generated not
with a template, but with a collection of snippets, which are joined
and checked using a Makefile.  This allows extra configuration
snippets to be added in to the configuration.

If it is deemed necessary, sysadmins can add extra snippets to these
configurations.  The basic procedure is to read the configuration
file, and decide where the extra directives need to go.  This is made
easier by the fact that through the configuration files comments are
added showing where each part comes from. 

--------------------------------------------------
# ------------------------------------------------------------------------------
# /etc/exim4/symbiosis.d/10-acl/40-acl-check-mail/00-header
# ------------------------------------------------------------------------------

# ACL that is used after the MAIL command
acl_check_mail:

# ------------------------------------------------------------------------------
# /etc/exim4/symbiosis.d/10-acl/40-acl-check-mail/90-default
# ------------------------------------------------------------------------------

# Allow anything not already denied to connect
  accept
--------------------------------------------------

In this example, if an extra directive were required in this ACL,
then a file could be created in
[directory]'/etc/exim4/symbiosis.d/10-acl/40-acl-check-mail/', maybe
with the filename '10-do-stuff'.  To create the new configuration,
we'd then need to run @make@ in [directory]'/etc/exim4/'.  This would
regenerate '/etc/exim4/exim4.conf', and perform a basic syntax check.
If happy with the new configuration, then exim4 could be restarted.

The equivalent Dovecot configuration is in '/etc/dovecot/symbiosis.d/'
which generates '/etc/dovecot/dovecot.conf'.  The Backup2l
configuration is in [directory]'/etc/symbiosis/backup.d/conf.d/', which
generates '/etc/symbiosis/backup.d/backup2l.conf'.



