Installation¶
A single script installs the modules you choose: server extensions, zimlets, helper components and permissions. At the end the mail service restarts once.
Maintenance window
mailboxd restarts once at the end of the installation, so users see a short interruption. Install during a maintenance window.
Standard installation¶
- Copy the package to the server and unpack it:
tar xzf profelis-edition-installer-ubuntu22.tgz cd profelis-edition-installer - Start the installation:
sudo ./install.sh - Choose the modules to install. Your choice is written to
/etc/profelis-edition/modules.confand remembered on later runs. - Verification runs at the end; you should see PASS.
- Hard-reload the admin console (Ctrl+Shift+R). The Profelis modules appear under Tools and Migration.
Common options¶
| Option | What it does |
|---|---|
--look air |
Opens webmail with the Profelis Air look (--look classic for Classic). |
--modules a,b,c |
Installs only these modules without asking. |
--all-modules |
Installs all modules. |
--yes |
Applies the previous selection without asking. |
--verify |
Runs the health check only. |
--wire-postfix |
Connects DLP to mail transfer (with confirmation). |
--mobile-agent |
Installs the mobile agent on the Z-Push server. |
--ha |
Installs the high-availability helper. |
--skip-restart |
Does not restart mailboxd; do it yourself later. |
--interactive |
Opens the guided installation (needs a terminal). |
--no-menu |
Does not open the guided menu even on a terminal; goes straight to module selection. |
--alwayson-admin-cidr LIST |
Always On: IP addresses or CIDR ranges allowed to reach the admin console (7071), in addition to the cluster. |
--pre-zmsetup |
Applies the swatch hardening between the Zimbra packages and zmsetup (new installs). |
--remove-snmp |
Removes the optional zimbra-snmp package. |
--no-guard |
Skips the guard baseline. |
--force |
Continues past a refused check on purpose. |
--skip-companions |
Does not install the companion services. |
--help |
Prints every option, grouped, with copy-paste examples. |
Order on a new Zimbra installation
Install the Zimbra packages, then run sudo ./install.sh --pre-zmsetup, then zmsetup, then sudo ./install.sh. The installation fails if the system is still unpatched against the swatch log-injection issue.
Guided installation¶
When install.sh runs on a terminal without options (or with --interactive), it opens a step-by-step guide. A short menu comes first:
| Choice | What it does |
|---|---|
1 Install / update |
Asks for this machine's role and installs according to the answers. |
2 Verify |
Health check only (same as --verify). |
3 Upgrade to full HA |
Shown only when this machine has a profile without a witness (lab). |
4 Help |
Shows the --help output. |
0 Exit |
Exits without doing anything. |
Roles:
| Role | Asked | Installed |
|---|---|---|
| Single server | Modules | Profelis modules (today's installation). |
| Cluster: first node | Nodes and their IPs, witness and its IP, shared IP, blob store, OpenSearch heap, InnoDB buffer pool, Zimbra patch 604, modules | The profile is generated; Profelis modules, patch 604 and the Always On phases (database, ZooKeeper, OpenSearch, LDAP replication, object store, blob, ...). |
| Cluster: additional node | Where the profile is, the patch package on this machine, modules | Profelis modules, patch 604 and the Always On phases. |
| Witness server | Where the profile is | Witness components only: firewall, ZooKeeper, garbd, OpenSearch voting node, Ceph or Garage member. Zimbra is not needed; an unrelated Zimbra on the witness is left untouched. |
The database mode follows from the topology and is explained in the guide: with a witness, Galera + MaxScale (synchronous replication on two nodes, majority vote on the witness); without a witness, single (the Zimbra database on the first node).
Blob store options and their questions (ceph, garage and s3 need Zimbra PFE 10; on Zimbra 9 the installer refuses them, use nfs):
| Store | When | Extra questions |
|---|---|---|
ceph |
Cluster with a witness; installed automatically on two nodes and the witness. | Loop image size for a lab or production disks (their content is erased); optional cluster network. |
garage |
Cluster with a witness; a lighter object store. | Loop image size or data directory; optional capacity. |
s3 |
The organization's existing S3 service; nothing is installed. | Endpoint, bucket, region and the path of a credentials file. |
nfs |
Lab default. | Optional NFS export. |
S3 keys are never asked on screen
Write the keys to a file as access_key=... and secret_key=... lines and set its permissions with chmod 600. The guide asks only for the file path; the keys are never written to the screen or the command line.
For the OpenSearch heap and the InnoDB buffer pool a default is suggested from the machine's memory. For Zimbra patch 604 the zmpatch-*.tar.gz in the installer package is suggested; if the patch is already applied, type yok.
Every role shows a summary of what will be done and asks for confirmation before changing anything. The installation shows each step as [i/N]; steps that are already done are passed with zaten kurulu. If a step fails, the installation stops and prints the commands to resume where it stopped. In a cluster with a witness, the first node waits until you confirm the witness was installed first. At the end the next steps are printed: copy the profile to the other machines, then the witness first, then the first node, then the other nodes.
The guide opens only when there is a terminal, --yes is not given and none of --modules, --all-modules, --verify or any --alwayson-* option is present. Automation and scripts behave as before.
A cluster without a witness is for labs only
Without a witness server (none), the database, NFS, ZooKeeper and OpenSearch run on the first node only. The first node is a single point of failure; if it stops, the whole cluster stops. Use a witness server in production.
Always On options¶
| Option | What it does |
|---|---|
--alwayson-nodes A,B |
If there is no profile, generates it on this machine (first node A) and installs. |
--alwayson-witness W |
Witness server. none is a lab installation; a server name produces a full HA profile. |
--alwayson-witness-ip IP |
IP address of the witness server (if it is not in DNS). |
--alwayson-vip IP |
Shared IP address; when empty, an external load balancer is used. |
--alwayson-blob B |
Blob store: ceph, garage, s3 or nfs. Default ceph with a witness, nfs in a lab. |
--alwayson-set K=V |
Writes a setting to the profile; repeatable. Examples: blob.loop_size=20G, blob.devices=/dev/sdb,/dev/sdc, index.opensearch_heap=4g, db.innodb_buffer_pool=8G. |
--alwayson-s3-credentials FILE |
Key file for the s3 store (access_key= and secret_key= lines). |
--alwayson-profile FILE |
Profile path (default /etc/profelis-alwayson/profile.conf). |
--alwayson-upgrade-fullha W |
On the first node, upgrades a cluster without a witness to full HA with witness W, then runs the cluster step. |
--no-alwayson-cluster |
Skips the cluster step (jars and zimlets only). |
When Always On is selected and the blob store is ceph, garage or s3, the s3store module is added to the selection automatically. If the installer package contains a zmpatch-*.tar.gz, its path is written to the profile when the profile is generated.
On a machine without Zimbra, if a profile exists and this machine is the witness in it, install.sh runs only alwayson-install and exits with its result.
Examples¶
# Guided installation (any role)
sudo ./install.sh
# Single server, no questions, all modules
sudo ./install.sh --yes --all-modules
# Update (same module selection)
sudo ./install.sh --yes
# Add one module to the current selection
sudo ./install.sh --yes --modules "$(grep -v '^#' /etc/profelis-edition/modules.conf | paste -sd, -),waf"
# Verification only
sudo ./install.sh --verify
Always On, lab (no witness, NFS, one command on the first node):
sudo ./install.sh --yes --all-modules \
--alwayson-nodes posta1.zpe.profelis.net,posta2.zpe.profelis.net --alwayson-witness none
Always On, full HA with Ceph. Order: profile, witness, first node, other nodes. The profile must be at the same path on every machine.
# posta1 (first node): generate the profile (lab disks; in production --set blob.devices=/dev/sdb,/dev/sdc)
sudo scripts/alwayson/alwayson-install --profile /etc/profelis-alwayson/profile.conf --write-profile \
--nodes posta1.zpe.profelis.net,posta2.zpe.profelis.net --witness tanik.zpe.profelis.net \
--witness-ip 192.0.2.30 --vip 192.0.2.10 --blob ceph --set blob.loop_size=20G
# witness: fetch the profile and install the witness components
sudo install -d -m 0700 /etc/profelis-alwayson
sudo scp -p posta1.zpe.profelis.net:/etc/profelis-alwayson/profile.conf /etc/profelis-alwayson/profile.conf
sudo scripts/alwayson/alwayson-install --profile /etc/profelis-alwayson/profile.conf --yes
# posta1, then posta2 (copy the profile to posta2 first)
sudo ./install.sh --yes
With Garage or an enterprise S3 service the profile command is the same; only the store options change:
# Garage
... --blob garage --set blob.data_dir=/srv/garage-data --set blob.garage_capacity=500G
# Enterprise S3 (keys in a file)
... --blob s3 --set blob.s3_endpoint=https://s3.zpe.profelis.net --set blob.s3_bucket=zimbra \
--s3-credentials /root/s3.cred
Upgrading a lab cluster to full HA (posta1 is the first node):
# posta1
sudo scripts/alwayson/alwayson-install --profile /etc/profelis-alwayson/profile.conf --upgrade-fullha \
--witness tanik.zpe.profelis.net --witness-ip 192.0.2.30 --blob ceph --set blob.loop_size=20G --yes
# copy the profile to the witness and posta2; then install the witness, posta1, posta2 in that order
When a cluster step stops halfway, the installation prints the resume command in the form alwayson-install --profile ... --phase ... and then the command to run install.sh again; completed steps are skipped.
Details: Always On installation.