Skip to content

Unprivileged User Mode ​

On Linux systems with systemd, the CommuniGate Pro Server can run as the system user cgatepro with the primary group mail. Privileged operations required by the Server are allowed using Linux capabilities specified in the CommuniGate-nonroot.service unit file.

A new installation uses Unprivileged User Mode by default. An upgrade preserves the existing service and its Administrator settings. The Installer does not change existing data permissions. Switching modes is a separate Administrator procedure.

systemd assigns the user and capabilities before starting the Server. Running as root or with capabilities beyond CAP_NET_BIND_SERVICE produces a warning on the WebAdmin General page and in the Server Log.

Choosing a Mode During Package Installation ​

A new installation runs the Server as cgatepro:mail using CommuniGate-nonroot.service by default. The Installer creates the cgatepro user if missing. The mail group must exist.

DEB and RPM installation do not prompt for a mode. Use CGP_INSTALL_SERVICE to select a service explicitly. For example, for a new installation running as root:

sh
sudo env CGP_INSTALL_SERVICE=CommuniGate.service dpkg -i ./CGatePro-Linux.deb
sudo env CGP_INSTALL_SERVICE=CommuniGate.service rpm -Uvh ./CGatePro-Linux.rpm

Replace the package name with the actual name. The value CommuniGate-nonroot.service explicitly selects Unprivileged User Mode. A new installation enables automatic startup and starts the selected service. During an upgrade, this parameter identifies the existing service and does not switch modes. To change modes, follow the switching procedure.

Upgrading an Existing Installation ​

An upgrade preserves the existing service, its local settings and data permissions. It does not create a user or recursively change ownership. Manifesto preparation is the exception. A missing Manifesto is generated automatically. The contents of an existing regular file are preserved. See the Manifesto section for handling links and unsuitable permissions.

The service is identified by the running service, then by enabled startup and the saved choice. An older installation without these records retains CommuniGate.service. Its user settings are also preserved.

The existing service retains its automatic startup and masking settings. Startup during an upgrade depends on the package type:

  • DEB. The service state is saved before stopping it. A previously running service is restarted, while a stopped service remains stopped. When upgrading an older package that does not save this state, or if saving it fails, previous activity is unknown. The service is then started only if automatic startup is enabled, and the Installer prints a warning.
  • RPM. A running service is identified during installation of the new version and restarted after successful Manifesto preparation. A stopped service remains stopped, even if automatic startup is enabled.

Reinstallation with retained data or settings is not a new installation. If the previous service cannot be identified, the Installer reports this and skips automatic service configuration. Specify the existing service and repeat installation, for example:

sh
sudo env CGP_INSTALL_SERVICE=CommuniGate.service dpkg -i ./CGatePro-Linux.deb
sudo env CGP_INSTALL_SERVICE=CommuniGate.service rpm -Uvh --replacepkgs ./CGatePro-Linux.rpm

The RPM option --replacepkgs allows reinstalling a package version that is already installed. If the Installer reports conflicting service states, resolve the conflict first. CGP_INSTALL_SERVICE does not bypass this check.

Accepted values are CommuniGate.service, CommuniGate-nonroot.service and external. Use external when managing startup yourself. This choice is saved in /etc/CommuniGate/service-unit, and the Installer neither enables nor starts the packaged services. The parameter does not switch an already detected service to another one.

Locating the Base Directory ​

The Installer and the manifest utility locate the base directory using running Server arguments or service settings. If no path is specified, the existing /var/CommuniGate is used. A new installation creates this directory if needed.

For a custom configuration, specify an absolute path using CGP_BASE_DIR. It takes precedence over automatic discovery:

sh
sudo env CGP_BASE_DIR=/srv/CommuniGate dpkg -i ./CGatePro-Linux.deb
sudo env CGP_BASE_DIR=/srv/CommuniGate rpm -Uvh ./CGatePro-Linux.rpm
sudo env CGP_BASE_DIR=/srv/CommuniGate /opt/CommuniGate/manifest

CGP_BASE_DIR does not change Server startup arguments. The path must match --Base or --CGateBase in the service settings. During an upgrade, the directory must exist and be accessible, including mounted storage.

If Service Preparation or Startup Fails ​

If the service cannot be identified, the base directory cannot be found, or Manifesto preparation fails, the Installer prints the reason to the console. Installation of executable files continues, while automatic service configuration or startup is skipped.

Resolve the reported problem, repeat Manifesto preparation if necessary, and start the selected service. Check its status and Log:

sh
systemctl status CommuniGate-nonroot.service
journalctl -u CommuniGate-nonroot.service -b

For an existing installation, use its service name. Successful package installation does not by itself mean that the Server is running.

Preparation ​

Run the preparation and mode switching commands below as the super-user. The examples use the default paths: /opt/CommuniGate for the application directory and /var/CommuniGate for the base directory. Replace these paths if your installation uses different directories.

  • Check the system user:

    sh
    getent passwd cgatepro
    id cgatepro

    When switching from root, create the user if missing. If the account was deleted from an existing installation, restore it with its original UID.

    sh
    useradd --system --gid mail --home-dir /var/CommuniGate --no-create-home --shell /usr/sbin/nologin cgatepro

    Adjust --home-dir for a different base directory and check the path to nologin on your system (for example, /sbin/nologin). Review an existing account instead of creating it again. A separate cgatepro group is not required.

  • Check the settings of both services:

    sh
    systemctl cat CommuniGate.service CommuniGate-nonroot.service

    Copy the required startup parameters and resource limits to the new service settings using systemctl edit CommuniGate-nonroot.service. Overrides for CommuniGate.service are not applied to the other service automatically. Keep User=cgatepro, Group=mail, and the capability settings of the new service. The supplied service already specifies --UseSystemPorts YES for system ports.

    The base directory is selected by the --Base or --CGateBase option in SUPPLPARAMS. The systemd WorkingDirectory setting does not replace these startup options. Remove --dropRoot from both service configurations: startup fails if this removed option is specified.

    By default, both services read environment variables from /var/CommuniGate/Startup.sh. If you move this file, change EnvironmentFile in both services. When using Environment=SUPPLPARAMS instead of the file, clear EnvironmentFile as shown in startup environment settings. Startup.sh is read as a set of environment variables, not executed as a shell script.

  • If external INBOX files are used, configure access to them before starting the service for unprivileged user mode.

  • Check the capabilities required by your Helper Programs. Additional privileges are specified in the service settings.

  • For shared Cluster storage, use matching numeric UIDs for cgatepro and GIDs for mail on all nodes. Identical names do not guarantee identical identifiers.

Shared Storage and NFS ​

Before switching modes, use systemctl edit to make the service wait for storage mounts, for example:

ini
[Unit]
RequiresMountsFor=/var/CommuniGate

Use the actual storage path. Matching numeric UIDs/GIDs and access to files must be configured on every node and on the storage server. If NFS root squashing prevents assigning root:mail to the Manifesto, prepare it on the storage server. The Installer does not disable root squashing. Check mount availability before starting the Server. Package installation does not itself guarantee that the data volume is mounted.

Switching to Unprivileged User Mode ​

Stop both services and any other processes modifying the base directory. For shared storage, stop all Cluster nodes accessing it:

sh
systemctl stop CommuniGate.service CommuniGate-nonroot.service

The script checks for local processes named CGServer before proceeding. It cannot verify that Helper Programs or other Cluster nodes have stopped.

Prepare the Manifesto before changing ownership. Review the settings for Helper Programs, Execute Rules, CGI programs and other external programs. If the Manifesto is missing, generate it from the reviewed configuration as root:

sh
CGP_BASE_DIR=/var/CommuniGate /opt/CommuniGate/manifest

Review the resulting list. An existing file owned by another user or writable by group or others is rejected by the utility without modification. After stopping all writers, review such a file and explicitly prepare it as root:mail, 0640 as described here. Every service requires a valid Manifesto regardless of its process UID.

Assign ownership and permissions to the base directory:

sh
bash /opt/CommuniGate/nonroot.sh

The nonroot.sh script sets directory permissions to 2770, preserves read, write and execute permissions of regular files, and handles the Manifesto separately as root:mail, 0640, excluding it from the recursive ownership and permission changes. Package installation does not apply this operation to existing data. Ensure that the mail group has the same GID on every node before switching modes.

The default base directory is /var/CommuniGate. For another location, specify --base /path/to/base. The default owner is cgatepro:mail; --mode root selects root:mail.

Switch services:

sh
systemctl disable CommuniGate.service
systemctl mask CommuniGate.service
systemctl unmask CommuniGate-nonroot.service
systemctl daemon-reload
systemctl enable --now CommuniGate-nonroot.service

After successful startup, record the selected service as root:

sh
install -d -m 0755 -o root -g root /etc/CommuniGate
install -m 0600 -o root -g root /dev/null /etc/CommuniGate/service-unit
printf '%s\n' 'CommuniGate-nonroot.service' > /etc/CommuniGate/service-unit

Wait 10-15 seconds and check startup:

sh
systemctl status CommuniGate-nonroot.service
journalctl -u CommuniGate-nonroot.service -n 100 --no-pager
pid=$(systemctl show CommuniGate-nonroot.service -p MainPID --value)
grep -E '^(Uid|Gid|Groups|Cap)' /proc/"$pid"/status
ss -ltnp 'sport = :25'

All values on the Uid line should match cgatepro; values on the Gid line should match mail. Check Listeners, data access, and Helper Programs. A new installation also requires Initial Configuration, including setting the postmaster password.

File Ownership ​

nonroot.sh assigns cgatepro:mail ownership to the entire base directory (root:mail with --mode root). Directories receive permissions 2770. Read, write and execute permissions of regular files are preserved, but changing ownership may clear setuid/setgid bits on executable files. Directory setgid is applied after changing ownership. Nested mounted file systems are also processed. Changing ownership of a hard-linked file affects all its names, including those outside the base directory.

By default, the script changes ownership of symbolic links themselves but does not process their targets. If links are found, it prints one summary warning when it exits.

To process link targets as well, add --follow-symlinks:

sh
bash /opt/CommuniGate/nonroot.sh --follow-symlinks

With this option, the script changes ownership of files referenced by links and traverses target directories, including those outside the base directory. Directories in these trees also receive permissions 2770. Before running the script, review the link targets and stop processes modifying that data. The option can be combined with --base and --mode root.

The exception is Settings/ChildProcs.data. It must remain a regular file owned by root:mail, with permissions 0640 and no additional hard links. Settings must not be a symbolic link. The --follow-symlinks option does not remove these requirements. The Manifesto is also excluded from the recursive ownership and permission changes when accessed through another symbolic link. The script does not create a missing Manifesto. Prepare it using the manifest utility before changing ownership.

Traversal fails if a symbolic link cycle is detected. If an error occurs, changes may have been partially applied. Resolve the problem and rerun the script before starting the Server.

External INBOX Access ​

This setup is needed only for Legacy Mailboxes stored outside the base directory. The Domain selects the path template (for example, /var/mail/*), while use of an external INBOX is enabled for individual Accounts. The Server needs both read and write access.

Before changing permissions, stop the Server and local mail applications using these files. Run the following commands as root. The example assumes the mailbox /var/mail/ivan already exists and belongs to OS user ivan; replace the name with the required user:

sh
chown root:mail /var/mail
chmod 2775 /var/mail
chgrp mail /var/mail/ivan
chmod 0660 /var/mail/ivan

The directory permits the mail group to create files, and its setgid bit makes new files inherit that group. Other users retain directory traversal access so that local mail applications can access their users' mailboxes. The mailbox owner remains ivan; both that user and the mail group can read and write the file. Repeat the last two commands for each external INBOX used by the Server. Members of mail receive access to these mailboxes and write access to the shared directory; reserve membership for trusted accounts.

Check access as the service user:

sh
runuser -u cgatepro -g mail -- sh -ec '
  test -x /var/mail
  test -w /var/mail
  test -r /var/mail/ivan
  test -w /var/mail/ivan
  echo "External INBOX access OK"
'

If mailboxes are stored elsewhere, adapt the paths and provide directory traversal permission on every parent directory. Local delivery and mail applications must preserve group mail and group read/write permissions when creating or replacing mailbox files. Directory setgid provides group inheritance, but does not add read/write permissions to a file created with mode 0600. CAP_CHOWN is not enabled by default. Existing mailboxes with the required access permissions can be used without it. If an external INBOX is missing, the Server tries to create the file and assign the corresponding OS user as owner. Without CAP_CHOWN, changing ownership to another UID fails, the newly created file is removed, and INBOX creation fails. Create the file in advance with the required OS user as owner and grant access through group mail, or add CAP_CHOWN to both service settings as described below. Permissions on the /var/mail directory alone do not allow changing file ownership.

The nonroot.sh script does not perform the external INBOX access setup described above. By default, it processes only the base directory. With --follow-symlinks, it also changes ownership and directory permissions through links from that directory, so check whether they lead to /var/mail or external INBOX files before running the script. After applying the settings, start the Server and check delivery and access to the external INBOX.

Capabilities and Helper Programs ​

The supplied service sets the following capabilities in AmbientCapabilities and CapabilityBoundingSet:

CapabilityPurpose
CAP_NET_BIND_SERVICEListeners on ports below 1024

The following capabilities are not enabled in the supplied service. Add them only for the functions you use:

CapabilityRequired for
CAP_SETUIDStarting child programs as another OS user, including the Execute Rule action with OSUserName specified
CAP_SETGIDSetting the primary and supplementary groups of child processes
CAP_KILLTerminating child processes with a different UID
CAP_CHOWNCreating missing external Unix INBOX files and assigning the corresponding OS user as owner
CAP_NET_ADMINManaging IPVS and network settings through IPVSHelper
CAP_NET_RAWRunning arping and performing RAW/PACKET socket operations from IPVSHelper

Starting a program as another OS user requires both capabilities: CAP_SETUID changes the UID, while CAP_SETGID sets the primary and supplementary groups. Without either capability, the operation fails. Also add CAP_KILL to terminate these child processes. Child processes running with the same UID as the Server can be terminated without CAP_KILL. To configure starting and terminating programs as another user, run systemctl edit CommuniGate-nonroot.service and add:

ini
[Service]
AmbientCapabilities=CAP_SETUID CAP_SETGID CAP_KILL
CapabilityBoundingSet=CAP_SETUID CAP_SETGID CAP_KILL

On ordinary execution, a child program inherits the Server groups without requiring CAP_SETGID. The mail group is assigned by systemd. If OSUserName is explicitly specified, the Server sets the groups again even for its own cgatepro user, so CAP_SETGID is required in that case.

For automatic creation of external INBOX files, similarly add CAP_CHOWN to both settings. For IPVSHelper, add:

ini
[Service]
AmbientCapabilities=CAP_NET_ADMIN CAP_NET_RAW
CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_RAW

CAP_NET_RAW is not required by standard Server TCP/UDP Listeners. Additional Helper Programs may have their own capability requirements.

Helper Programs, CGI, programs started by the Execute Rule action and other child processes inherit Server capabilities on ordinary execution. These capabilities are retained when another OS user is selected. In unprivileged user mode, selecting another OS user with target UID 0 is prohibited: the Server returns an error before creating the child process. Use CommuniGate.service to run programs as root; its previous behavior is preserved.

If a Helper Program requires additional privileges, add them to both settings using systemctl edit CommuniGate-nonroot.service. For example:

ini
[Service]
AmbientCapabilities=CAP_SYS_NICE
CapabilityBoundingSet=CAP_SYS_NICE

Additional lines extend the supplied lists. To remove a capability, first reset the corresponding list with an empty assignment, then specify the complete remaining set. Apply the changes:

sh
systemctl daemon-reload
systemctl restart CommuniGate-nonroot.service

These privileges apply to the entire Server and its child programs, not just one Helper Program.

For Helper Programs using iptables-legacy, also provide access to the shared /run/xtables.lock. To create the file when absent and preserve its permissions after reboot, add the following rule to /etc/tmpfiles.d/communigate-ipvs.conf (review any existing rules first):

text
f /run/xtables.lock 0660 root mail -

Apply it as root with systemd-tmpfiles --create /etc/tmpfiles.d/communigate-ipvs.conf. Keep the shared lock file; do not replace it with a separate lock or delete it while in use.

Preventing New Privileges ​

The supplied service for unprivileged user mode sets NoNewPrivileges=yes. When executing programs, the Server and its child processes cannot gain additional privileges through setuid/setgid bits or capabilities assigned to executable files (file capabilities). Child processes inherit this restriction and cannot clear it themselves.

If a Helper Program requires privileges acquired specifically through setuid/setgid or file capabilities, check whether it can operate with capabilities assigned through the service settings. These privileges will apply to the entire Server and its child processes. If this is unsuitable, the Administrator can disable the restriction using systemctl edit CommuniGate-nonroot.service:

ini
[Service]
NoNewPrivileges=no

This exception applies to the entire service and its child processes. It does not remove CapabilityBoundingSet restrictions or the prohibition on running the Execute action as UID 0 in unprivileged user mode. To apply the change, run:

sh
systemctl daemon-reload
systemctl restart CommuniGate-nonroot.service

Returning to Root ​

Stop both services and other processes modifying the base directory. For shared storage, stop the corresponding Cluster nodes:

sh
systemctl stop CommuniGate.service CommuniGate-nonroot.service

To restore root:mail ownership, run:

sh
bash /opt/CommuniGate/nonroot.sh --mode root

For a nonstandard base directory, add --base /path/to/base. The existing manifesto retains root:mail and mode 0640.

Copy the current startup parameters to CommuniGate.service. Check systemctl cat CommuniGate.service and remove any local User= override that selects an unprivileged user. The supplied service does not specify a user, so the service runs as root. Enable the service:

sh
systemctl disable CommuniGate-nonroot.service
systemctl mask CommuniGate-nonroot.service
systemctl unmask CommuniGate.service
systemctl daemon-reload
systemctl enable --now CommuniGate.service

After successful startup, record the selected service as root:

sh
install -d -m 0755 -o root -g root /etc/CommuniGate
install -m 0600 -o root -g root /dev/null /etc/CommuniGate/service-unit
printf '%s\n' 'CommuniGate.service' > /etc/CommuniGate/service-unit

Wait 10-15 seconds, then check systemctl status CommuniGate.service, the Log, Listeners, and Helper Programs. Repeat permission preparation when switching to unprivileged user mode again. Running as root may have created new root-owned files.