Difference between revisions of "AppSuite:OX Guard"

(Added Update Repository)
m (Version Matrix)
(48 intermediate revisions by 5 users not shown)
Line 1: Line 1:
= OX Guard =
+
= OX Guard (Version 2.4 - 2.8) =
  
OX Guard is a fully integrated security add-on to OX App Suite that provides end users with a flexible email and file encryption solution. OX Guard is a highly scalable, multi server, feature rich solution that is so simple-to-use that end users will actually use it. With a single click a user can take control of their security and send secure emails and share encrypted files. This can be done from any device to both OX App Suite and non-OX App Suite users.  
+
For previous versions of OX Guard, please click here
 +
* [[AppSuite:OX_Guard_2-0|Installation and information of OX Guard 2.0 - 2.2]]
 +
 
 +
If upgrading from 2.0 or 2.2, please see the following article
 +
* [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]]
 +
 
 +
== Overview ==
 +
 
 +
OX Guard is a fully integrated security add-on to OX App Suite that provides end users with a flexible email and file encryption solution. OX Guard is a highly scalable, multi server, feature rich solution that is so simple-to-use that end users will actually use it. With a single click a user can take control of their security and send secure emails and share encrypted files. This can be done from any device to both OX App Suite and non-OX App Suite users.
  
 
OX Guard uses standard PGP encryption for the encryption of email and files. PGP has been around for a long time, yet has not really caught on with the masses. This is generally blamed on the confusion and complications of managing the keys, understanding trust, PGP format types, and lack of trusted central key repositories. Guard simplifies all of this, making PGP encryption as easy as a one click process, with no keys to keep track of, yet the options of advanced PGP management for those that know how.
 
OX Guard uses standard PGP encryption for the encryption of email and files. PGP has been around for a long time, yet has not really caught on with the masses. This is generally blamed on the confusion and complications of managing the keys, understanding trust, PGP format types, and lack of trusted central key repositories. Guard simplifies all of this, making PGP encryption as easy as a one click process, with no keys to keep track of, yet the options of advanced PGP management for those that know how.
Line 10: Line 18:
 
* To setup a single Guard instance on an existing Open-Xchange installation, no cluster
 
* To setup a single Guard instance on an existing Open-Xchange installation, no cluster
 
* To use the database service on the existing Open-Xchange installation for Guard, no replication
 
* To use the database service on the existing Open-Xchange installation for Guard, no replication
* To provide a basic configuration setup, no mailserver configuration
+
* To provide a basic configuration setup, no mail server configuration
  
== Key features ==
+
=== Key Features ===
  
 
* Simple security at the touch of a button
 
* Simple security at the touch of a button
Line 22: Line 30:
 
* Uses proven PGP security
 
* Uses proven PGP security
  
== Availability ==
+
=== Availability ===
  
 
If an OX App Suite customer would like to evaluate OX Guard integration, the first step is to contact OX Sales. OX Sales will then work on the request and send prices and license/API (for the hosted infrastructure) key details to the customer.
 
If an OX App Suite customer would like to evaluate OX Guard integration, the first step is to contact OX Sales. OX Sales will then work on the request and send prices and license/API (for the hosted infrastructure) key details to the customer.
  
== Requirements ==
+
=== Requirements ===
  
Please review following URL for remaining requirements
+
Please review [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#OX_Guard OX Guard Requirements] for a full list of requirements.
  
Please review [[AppSuite:OX_System_Requirements#OX_Guard|OX Guard Requirements]] for a full list of requirements.
+
Since OX Guard is a Microservice it can either be added to an existing Open-Xchange installation or it can be deployed on a dedicated environment. OX App Suite v7.8.1 or later is required to operate this extension both in a single or multi server environments.
  
Since OX Guard is a Microservice it can either be added to an existing Open-Xchange installation or it can be deployed on a dedicated environment without having any of the other Open-Xchange App Suite core services installed. OX App Suite v7.6.0 or later is required to operate this extension both in a single or multi server environments.
+
==== Prerequisites ====
  
Prerequisites:
 
 
* Open-Xchange REST API
 
* Open-Xchange REST API
 
* Grizzly HTTP connector (open-xchange-grizzly)
 
* Grizzly HTTP connector (open-xchange-grizzly)
 
* A supported Java Virtual Machine (Java 7)
 
* A supported Java Virtual Machine (Java 7)
* An Open-Xchange App Suite installation v7.6.0 or later
+
* An Open-Xchange App Suite installation v7.8.1 or later
* Please Note: To get access to the latest minor features and bug fixes, you need to have a valid license. The article [[AppSuite:UpdatingOXPackages|Updating OX-Packages]] explains how that can be done.
+
* Please Note: To get access to the latest minor features and bug fixes, you need to have a valid license. The article [https://oxpedia.org/wiki/index.php?title=AppSuite:UpdatingOXPackages Updating OX-Packages] explains how that can be done.
  
== Important Notes ==
+
==== Version Matrix ====
 +
{|
 +
! style="text-align:left;"| Core Version
 +
! Guard Version
 +
|-
 +
|7.8.1
 +
|2.4.0 or 2.4.2
 +
|-
 +
|7.8.2
 +
|2.4.2
 +
|-
 +
|7.8.3
 +
|2.6.0
 +
|-
 +
|7.8.4
 +
|2.8.0
 +
|-
 +
|7.10.0
 +
|2.10.0
 +
|-
 +
|7.10.1
 +
|2.10.1
 +
|-
 +
|7.10.2
 +
|2.10.2
 +
|-
 +
|}
  
=== Customization ===
+
=== Important Notes ===
  
OX Guard version supports branding / theming using the configuration cascade, defining a templateID for a user or context.  Additional details will be provided in customization documentation. Check bottom of this page.
+
==== Customisation ====
  
 +
OX Guard version supports branding / theming using the configuration cascade, defining a templateID for a user or context. Check the [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization OX Guard Customisation] article for more details.
  
=== Mail Resolver ===
+
==== Mail Resolver ====
  
 
READ THIS VERY CAREFULLY; BEFORE PROCEEDING WITH GUARD INSTALLATION!
 
READ THIS VERY CAREFULLY; BEFORE PROCEEDING WITH GUARD INSTALLATION!
  
The Guard installation must be able to determine if an email recipient is a local OX user or if it should be a guest account. The default MailResolver uses the context domain name to do this. On many installations, domains may extend across multiple context and multiple database shards. In these cases, the default MailResolver won't work. In addition, if a custom authentication package is used, the Mail Resolver will likely not work.
+
The Guard installation must be able to determine if an email recipient is a local OX user or if it should be a guest account. The default MailResolver uses the context domain name to do this. On many installations, domains may extend across multiple context and multiple database shards. In these cases, the default MailResolver won't work. In addition, if a custom authentication package is used, the Mail Resolver will likely not work.
 
 
Be sure to test the mail resolver using
 
  
/opt/open-xchange/guard/sbin/guard test email@domain
+
Once Guard is installed, please be sure to test the mail resolver using:
  
 +
<source lang="bash">/opt/open-xchange/sbin/guard test email@domain</source>
 
to see if the mail Resolver works.
 
to see if the mail Resolver works.
  
If the test does not work, you will likely need a custom Mail Resolver. Please see [[AppSuite:GuardMailResolver| Mail Resolver page]]
+
If the test does not work, you will likely need a custom Mail Resolver. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver Mail Resolver] page
  
 
This resolver software ''depends heavily on your local deployment''.
 
This resolver software ''depends heavily on your local deployment''.
  
= Download and Installation =
+
== Download and Installation ==
  
 
=== General ===
 
=== General ===
The installation of the open-xchange-rest package which is required for Guard will eventually execute database update tasks if installed and activated. Please take this into account.
 
  
There are several components to the Guard service. They can be all installed on the same server as the OX backend, or on a separate server.
+
The installation of the <code>open-xchange-guard-backend-plugin</code> package which is required for Guard and the main <code>open-xchange-guard</code> package in version 2.4.0 or higher will eventually execute database update tasks if installed and activated. Please take this into account.
 +
 
 +
There are several components to the Guard service. They can be all installed on the same server as the OX middleware or on a separate server.
  
The components required for the OX backend are: open-xchange-rest, open-xchange-guard-backend-plugin
+
The components required for the OX middleware are: <code>open-xchange-rest</code>, <code>open-xchange-guard-backend-plugin</code> and <code>open-xchange-guard-ui</code>.
  
The components required for the OX frontend are: open-xchange-guard-ui open-xchange-guard-ui-static and optionally open-xchange-guard-help-en-us (or preferred language for help files)
+
The components required for the OX frontend are: <code>open-xchange-guard-ui-static</code> <code>open-xchange-guard-reader</code> and optionally <code>open-xchange-guard-help-en-us</code> (or preferred language for help files).
  
The components required for the Guard server (may be on same as the backend) open-xchange-guard
+
The components required for the Guard server <code>open-xchange-guard</code> and either <code>open-xchange-guard-file-storage</code> or <code>open-xchange-guard-s3-storage</code> depending on what storage you want to use. The examples below make use of the <code>open-xchange-guard-file-storage</code>. Adjust the commands accordingly to fit your needs. In addition <code>open-xchange</code> and <code>open-xchange-core</code> are required to run OX Guard.
  
=== Redhat Enterprise Linux 6 or CentOS 6 ===
+
=== Debian Linux 8.0 (Jessie) ===
  
If not already done, add the following repositories to your Open-Xchange yum configuration:
+
If not already done, add the following repositories to your Open-Xchange apt configuration:
  
  {{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products|pc2n=rhelname|pc2v=RHEL6|guard/stable/guard}}
+
  deb https://software.open-xchange.com/products/guard/stable/guard/DebianJessie /
 +
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>
  
if you have a valid maintenance subscription, please uncomment the
+
and then run for a single node installation:
following and add the ldb account data to the url so that the most recent
 
packages get installed
 
  
  {{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|guard/stable/guard/updates}}
+
  $ apt-get update
 +
$ apt-get install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin open-xchange-guard-reader</source>
  
and run
+
or the following for a distributed installation:
  
  $ yum update
+
  $ apt-get update
  $ yum install open-xchange-rest open-xchange-guard open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin
+
  $ apt-get install open-xchange-guard open-xchange-guard-file-storage</source>
 +
The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware.  The packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).
  
=== Redhat Enterprise Linux 7 or CentOS 7 ===
+
=== RedHat Enterprise Linux 6 or CentOS 6 ===
  
 
If not already done, add the following repositories to your Open-Xchange yum configuration:
 
If not already done, add the following repositories to your Open-Xchange yum configuration:
  
  {{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products|pc2n=rhelname|pc2v=RHEL7|guard/stable/guard}}
+
  [open-xchange-guard-stable-guard]
 +
name=Open-Xchange-guard-stable-guard
 +
baseurl=https://software.open-xchange.com/products/guard/stable/guard/RHEL6/
 +
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
 +
enabled=1
 +
gpgcheck=1
 +
metadata_expire=0m
  
if you have a valid maintenance subscription, please uncomment the
+
[ox-backend]
following and add the ldb account data to the url so that the most recent
+
name=Open-Xchange-backend
packages get installed
+
baseurl=https://software.open-xchange.com/products/appsuite/stable/backend/RHEL6/
 +
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
 +
enabled=1
 +
gpgcheck=1
 +
metadata_expire=0m</source>
  
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|guard/stable/guard/updates}}
+
and then run for a single node installation:
  
and run
+
$ yum update
 +
$ yum install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin open-xchange-guard-reader</source>
 +
or the following for a distributed installation:
  
 
  $ yum update
 
  $ yum update
  $ yum install open-xchange-rest open-xchange-guard open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin
+
  $ yum install open-xchange-guard open-xchange-guard-file-storage</source>
 +
The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware.  The packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).
  
=== Debian GNU/Linux 7.0 ===
+
=== Redhat Enterprise Linux 7 or CentOS 7 ===
  
If not already done, add the following repositories to your Open-Xchange apt configuration:
+
If not already done, add the following repositories to your Open-Xchange yum configuration:
  
  {{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products|pc2n=debianname|pc2v=DebianWheezy|guard/stable/guard}}
+
  [open-xchange-guard-stable-guard]
 +
name=Open-Xchange-guard-stable-guard
 +
baseurl=https://software.open-xchange.com/products/guard/stable/guard/RHEL7/
 +
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
 +
enabled=1
 +
gpgcheck=1
 +
metadata_expire=0m
  
if you have a valid maintenance subscription, please uncomment the
+
[ox-backend]
following and add the ldb account data to the url so that the most recent
+
name=Open-Xchange-backend
packages get installed
+
baseurl=https://software.open-xchange.com/products/appsuite/stable/backend/RHEL7/
 +
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
 +
enabled=1
 +
gpgcheck=1
 +
metadata_expire=0m</source>
  
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|guard/stable/guard/updates}}
+
and then run for a single node installation:
  
and run
+
$ yum update
 +
$ yum install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin open-xchange-guard-reader</source>
 +
or the following for a distributed installation:
  
  $ apt-get update
+
  $ yum update
  $ apt-get install open-xchange-rest open-xchange-guard open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin
+
  $ yum install open-xchange-guard open-xchange-guard-file-storage</source>
 
 
=== Debian GNU/Linux 8.0 ===
 
 
 
If not already done, add the following repositories to your Open-Xchange apt configuration:
 
 
 
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products|pc2n=debianname|pc2v=DebianJessie|guard/stable/guard}}
 
 
 
if you have a valid maintenance subscription, please uncomment the
 
following and add the ldb account data to the url so that the most recent
 
packages get installed
 
 
 
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|guard/stable/guard/updates}}
 
 
 
and run
 
  
$ apt-get update
+
The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware.  The packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).
$ apt-get install open-xchange-rest open-xchange-guard open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin
 
  
=== SUSE Linux Enterprise Server 11 ===
+
=== SUSE Linux Enterprise Server 11 (valid until v2.4.2) ===
  
 
Add the package repository using zypper if not already present:
 
Add the package repository using zypper if not already present:
  
  {{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products|pc2n=susename|pc2v=SLES11|guard/stable/guard}}
+
  $ zypper ar https://software.open-xchange.com/products/guard/2.4.2/guard/SLES11 guard-stable-guard
 +
$ zypper ar https://software.open-xchange.com/products/appsuite/7.8.2/backend/SLES11 ox-backend</source>
  
if you have a valid maintenance subscription, please uncomment the
+
and then run for a single node installation:
following and add the ldb account data to the url so that the most recent
 
packages get installed
 
  
  {{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|guard/stable/guard/updates}}
+
  $ zypper ref
 
+
$ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin open-xchange-guard-reader</source>
and run
+
or the following for a distributed installation:
  
 
  $ zypper ref
 
  $ zypper ref
  $ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin
+
  $ zypper in open-xchange-guard open-xchange-guard-file-storage</source>
 
+
The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middlewareThe packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).
Guard requires Java 1.7, which will be installed through the Guard packages, still SUSE Linux Enterprise Server 11 will not use Java 1.7 by default. Therefor we have to set Java 1.7 as the default instead of Java 1.6:
 
 
 
$ update-alternatives --config java
 
 
 
Now select the Java 1.7 JRE, example:
 
 
 
There are 2 alternatives which provide `java'.
 
 
 
  Selection    Alternative
 
  -----------------------------------------------
 
*        1    /usr/lib64/jvm/jre-1.6.0-ibm/bin/java
 
  +        2    /usr/lib64/jvm/jre-1.7.0-ibm/bin/java
 
 
Press enter to keep the default[*], or type selection number: 2
 
Using '/usr/lib64/jvm/jre-1.7.0-ibm/bin/java' to provide 'java'.
 
  
 
=== SUSE Linux Enterprise Server 12 ===
 
=== SUSE Linux Enterprise Server 12 ===
Line 182: Line 211:
 
Add the package repository using zypper if not already present:
 
Add the package repository using zypper if not already present:
  
  {{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products|pc2n=susename|pc2v=SLE_12|guard/stable/guard}}
+
  $ zypper ar https://software.open-xchange.com/products/guard/stable/guard/SLE_12 guard-stable-guard
 +
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLE_12 ox-backend</source>
  
if you have a valid maintenance subscription, please uncomment the
+
and then run for a single node installation:
following and add the ldb account data to the url so that the most recent
 
packages get installed
 
  
  {{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|guard/stable/guard/updates}}
+
  $ zypper ref
 +
$ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-reader</source>
  
and run
+
or the following for a distributed installation:
  
 
  $ zypper ref
 
  $ zypper ref
  $ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-ui open-xchange-guard-ui-static
+
  $ zypper in open-xchange-guard open-xchange-guard-file-storage</source>
 
 
Guard requires Java 1.7, which will be installed through the Guard packages, still SUSE Linux Enterprise Server 11 will not use Java 1.7 by default. Therefor we have to set Java 1.7 as the default instead of Java 1.6:
 
 
 
$ update-alternatives --config java
 
 
 
Now select the Java 1.7 JRE, example:
 
  
  There are 2 alternatives which provide `java'.
+
The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).
  
  Selection    Alternative
 
-----------------------------------------------
 
*        1    /usr/lib64/jvm/jre-1.6.0-ibm/bin/java
 
  +        2    /usr/lib64/jvm/jre-1.7.0-ibm/bin/java
 
 
Press enter to keep the default[*], or type selection number: 2
 
Using '/usr/lib64/jvm/jre-1.7.0-ibm/bin/java' to provide 'java'.
 
  
 
=== Univention Corporate Server ===
 
=== Univention Corporate Server ===
Line 215: Line 231:
 
If you have purchased the OX App Suite for UCS, the OX Guard is part of the offering. OX Guard is available in the Univention App Center. Please check the UMC module App Center for the installation of the OX Guard at your already available environment.
 
If you have purchased the OX App Suite for UCS, the OX Guard is part of the offering. OX Guard is available in the Univention App Center. Please check the UMC module App Center for the installation of the OX Guard at your already available environment.
  
'''Please note:''' By default, OX Guard generates the link to the secure content for external recipients on the basis of the local fully qualified domain name (FQDN). If the local FQDN is not reachable from the internet, it has to be specified manually. This can be done by setting a UCR variable, e.g. via the UMC module "Univention Configuration Registry". The variable has to contain the external FQDN of the OX Guard system:
+
Please note: By default, OX Guard generates the link to the secure content for external recipients on the basis of the local fully qualified domain name (FQDN). If the local FQDN is not reachable from the Internet, it has to be specified manually. This can be done by setting a UCR variable, e.g. via the UMC module &quot;Univention Configuration Registry&quot;. The variable has to contain the external FQDN of the OX Guard system:
 
 
oxguard/cfg/guard.properties/com.openexchange.guard.externalEmailURL=HOSTNAME.DOMAINNAME
 
 
 
= Update OX Guard =
 
 
 
Before upgrading Guard to version 2.0.0 you need to install the package <code>open-xchange-guard-backend</code> on all groupware nodes used by Guard throught the REST api. In other words, every groupware node have <code>open-xchange-rest</code> installed, now needs to have <code>open-xchange-guard-backend</code> installed.
 
 
 
=== Redhat Enterprise Linux 6 or CentOS 6 ===
 
 
 
If not already done, add the following repositories to your Open-Xchange yum configuration:
 
 
 
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|guard/stable/guard/updates}}
 
 
 
and run
 
 
 
$ yum update
 
$ yum upgrade
 
 
 
After the new packages are installed, the guard process needs a restart:
 
 
 
<pre>$ /etc/init.d/open-xchange-guard restart</pre>
 
 
 
=== Redhat Enterprise Linux 7 or CentOS 7 ===
 
 
 
If not already done, add the following repositories to your Open-Xchange yum configuration:
 
 
 
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|guard/stable/guard/updates}}
 
 
 
and run
 
  
$ yum update
+
<source lang="bash">oxguard/cfg/guard.properties/com.openexchange.guard.externalEmailURL=HOSTNAME.DOMAINNAME</source>
$ yum upgrade
 
  
After the new packages are installed, the guard process needs a restart:
+
== Update OX Guard ==
  
<pre>$ /etc/init.d/open-xchange-guard restart</pre>
+
This section contains information about updating a 2.4.0 version (e.g. for patch fixes). Upgrading from prior versions is discussed in different articles. You can find more information in the '''Update OX Guard Versions &lt;= 2.2.x''' and '''Update OX Guard Versions &lt;= 2.0.x''' sections below.
  
=== Debian GNU/Linux 7.0 ===
+
=== Debian Linux 7.0 (Wheezy) (valid until v2.4.2) ===
  
 
If not already done, add the following repositories to your Open-Xchange apt configuration:
 
If not already done, add the following repositories to your Open-Xchange apt configuration:
  
  {{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|guard/stable/guard/updates}}
+
  deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/2.4.2/guard/updates/DebianWheezy /
 +
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/7.8.2/backend/DebianWheezy /</source>
  
Then run
+
Then run:
  
 
  $ apt-get update
 
  $ apt-get update
  $ apt-get dist-upgrade
+
  $ apt-get dist-upgrade</source>
  
 
If you want to see, what apt-get is going to do without actually doing it, you can run:
 
If you want to see, what apt-get is going to do without actually doing it, you can run:
  
  $ apt-get dist-upgrade -s
+
  $ apt-get dist-upgrade -s</source>
 
 
After the new packages are installed, the guard process needs a restart:
 
 
 
<pre>$ /etc/init.d/open-xchange-guard restart</pre>
 
  
=== Debian GNU/Linux 8.0 ===
+
=== Debian Linux 8.0 (Jessie) ===
  
 
If not already done, add the following repositories to your Open-Xchange apt configuration:
 
If not already done, add the following repositories to your Open-Xchange apt configuration:
  
  {{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|guard/stable/guard/updates}}
+
  deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianJessie /
 +
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>
  
Then run
+
Then run:
  
 
  $ apt-get update
 
  $ apt-get update
  $ apt-get dist-upgrade
+
  $ apt-get dist-upgrade</source>
  
 
If you want to see, what apt-get is going to do without actually doing it, you can run:
 
If you want to see, what apt-get is going to do without actually doing it, you can run:
  
  $ apt-get dist-upgrade -s
+
  $ apt-get dist-upgrade -s</source>
  
After the new packages are installed, the guard process needs a restart:
+
=== Redhat Enterprise Linux 6 or CentOS 6 ===
  
<pre>$ /etc/init.d/open-xchange-guard restart</pre>
+
If not already done, add the following repositories to your Open-Xchange yum configuration:
  
=== SUSE Linux Enterprise Server 11 ===
+
[open-xchange-guard-stable-guard-updates]
 +
name=Open-Xchange-guard-stable-guard-updates
 +
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/RHEL6/
 +
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
 +
enabled=1
 +
gpgcheck=1
 +
metadata_expire=0m
  
Add the package repository using zypper if not already present:
+
[ox-backend]
 +
name=Open-Xchange-backend
 +
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL6/
 +
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
 +
enabled=1
 +
gpgcheck=1
 +
metadata_expire=0m</source>
  
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|guard/stable/guard/updates}}
+
and then run:
  
and run
+
$ yum update
 +
$ yum upgrade</source>
  
$ zypper dup -r guard-stable-guard-backend-updates
+
=== Redhat Enterprise Linux 7 or CentOS 7 ===
$ zypper dup -r guard-stable-guard-ui-updates
+
 
 +
If not already done, add the following repositories to your Open-Xchange yum configuration:
  
You might need to run
+
[open-xchange-guard-stable-guard-updates]
 +
name=Open-Xchange-guard-stable-guard-updates
 +
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/RHEL7/
 +
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
 +
enabled=1
 +
gpgcheck=1
 +
metadata_expire=0m
  
  $ zypper ref
+
  [ox-backend]
 +
name=Open-Xchange-backend
 +
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL7/
 +
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
 +
enabled=1
 +
gpgcheck=1
 +
metadata_expire=0m</source>
  
to update the repository metadata before running ''zypper up''.
+
and then run:
  
After the new packages are installed, the guard process needs a restart:
+
$ yum update
 +
$ yum upgrade</source>
  
<pre>$ open-xchange-guard restart</pre>
 
  
 
=== SUSE Linux Enterprise Server 12 ===
 
=== SUSE Linux Enterprise Server 12 ===
  
Add the package repository using zypper if not already present:
+
Add the package repository using <code>zypper</code> if not already present:
  
  {{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|guard/stable/guard/updates}}
+
  $ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/SLE_12 guard-stable-guard-updates
 +
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLE_12 ox-backend</source>
  
and run
+
and then run:
  
 
  $ zypper dup -r guard-stable-guard-backend-updates
 
  $ zypper dup -r guard-stable-guard-backend-updates
  $ zypper dup -r guard-stable-guard-ui-updates
+
  $ zypper dup -r guard-stable-guard-ui-updates</source>
 
 
You might need to run
 
 
 
$ zypper ref
 
  
to update the repository metadata before running ''zypper up''.
+
You might need to run:
  
After the new packages are installed, the guard process needs a restart:
+
$ zypper ref</source>
  
<pre>$ open-xchange-guard restart</pre>
+
to update the repository metadata before running <code>zypper</code> up.
  
 
=== Univention Corporate Server ===
 
=== Univention Corporate Server ===
Line 337: Line 344:
 
If you have purchased the OX App Suite for UCS, the OX Guard is part of the offering. OX Guard is available in the Univention App Center. Please check the UMC module App Center for the update of the OX Guard.
 
If you have purchased the OX App Suite for UCS, the OX Guard is part of the offering. OX Guard is available in the Univention App Center. Please check the UMC module App Center for the update of the OX Guard.
  
=== Update OX Guard v1.2 to OX Guard v2.0.0 ===
+
=== Update OX Guard Versions &lt;= 2.2.x ===
 
 
IMPORTANT: '''''If you did not run GUARD 1.2 already, you DO NOT NEED to execute the "upgradePGP" command!'''''
 
 
 
If you have an existing Guard v1.2 database, and are upgrading to v2.0, additional PGP key table need to be created and populated.  Once the Guard package has been updated, type
 
 
 
/opt/open-xchange/guard/sbin/guard upgradePGP
 
 
 
This process will alter the needed database tables and populate the needed lookup tables.  Guard 1.2 can continue to run in the background.  Once complete, Guard 2.0 can be started.
 
 
 
= Configuration =
 
  
The following gives an overview of the most important settings to enable Guard for users on the Open-Xchange installation. Some of those settings have to be modified in order to establish the database and REST API access from the Guard service. All settings relating to the Guard backend component are located in the configuration file guard.properties located in /opt/open-xchange/guard/etc. The default configuration should be sufficient for a basic "up-and-running" setup (with the exception of defining the database username and password). Please refer to the inline documentation of the configuration file for more advanced options.  Additional information can be found here [[AppSuite:GuardConfiguration|Guard Configuration]]
+
If you are upgrading from a 2.2 version to 2.4, please read the [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]] article.
  
$ vim /opt/open-xchange/guard/etc/guard.properties
+
== Configuration ==
  
Open-Xchange config_db host - Guard will establish a connection to the config_db
+
The following gives an overview of the most important settings to enable Guard for users on the Open-Xchange installation. Some of those settings have to be modified in order to establish the database and REST API access from the Guard service. All settings relating to the Guard backend component are located in the configuration file <code>guard-core.properties</code> located in <code>/opt/open-xchange/etc</code>. The default configuration should be sufficient for a basic &quot;up-and-running&quot; setup (with the exception of defining the database username and password). Please refer to the inline documentation of the configuration file for more advanced options. Additional information can be found in the [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Configuration Guard Configuration] article.
  
com.openexchange.guard.configdbHostname=localhost
+
=== Basic Configuration ===
  
Guard database for storing Guard user information, main lookup tables
+
<source lang="bash">$ vim /opt/open-xchange/etc/guard-core.properties</source>
 +
Guard database for storing Guard user information, main lookup tables:
  
com.openexchange.guard.oxguardDatabaseHostname=localhost
+
<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname=localhost</source>
 +
Guard database that stores keys for guest users. May be the same as above. New guest shards will be created on this database as needed. If not supplied, will use the <code>oxguardDatabaseHostname</code>:
  
Guard database that stores keys for guest users. May be the same as above. New guest shards will be created on this database as needed. If not supplied, will use the oxguardDatabaseHostname
+
<source lang="bash">com.openexchange.guard.oxguardShardDatabase=localhost</source>
 +
Username and Password for the databases above:
  
com.openexchange.guard.oxguardShardDatabase=localhost
+
<source lang="bash">com.openexchange.guard.databaseUsername=openexchange
 +
com.openexchange.guard.databasePassword=db_password</source>
 +
Open-Xchange REST API host:
  
Username and Password for the databases above
+
<source lang="bash">com.openexchange.guard.restApiHostname=localhost</source>
 +
Open-Xchange REST API username and password (need to be defined in the OX backend in the &quot;Configure services&quot; below):
  
com.openexchange.guard.databaseUsername=openexchange
+
<source lang="bash">com.openexchange.guard.restApiUsername=apiusername
com.openexchange.guard.databasePassword=db_password
+
com.openexchange.guard.restApiPassword=apipassword</source>
 +
External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients:
  
Open-Xchange REST API host
+
<source lang="bash">com.openexchange.guard.externalEmailURL=URL_TO_OX</source>
 +
=== Middleware Configuration on OX Guard node ===
  
com.openexchange.guard.restApiHostname=localhost
+
If you are installing OX Guard on a node that until yet did not host an Open-Xchange middleware you have to additionally configure some parts of the following properties files:
  
Open-Xchange REST API username and password (need to be defined in the OX backend in the "Configure services" below)
+
* <code>configdb.properties</code>: information about the existing configuration database.
 +
* <code>server.properties</code>: information about the connections have to be set.
 +
* <code>system.properties</code>: at least <code>SERVER_NAME</code> should be set.
  
com.openexchange.guard.restApiUsername=apiusername
+
=== Sevices Configuration ===
com.openexchange.guard.restApiPassword=apipassword
 
  
External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients
+
==== Apache ====
  
com.openexchange.guard.externalEmailURL=URL_TO_OX
+
Configure the <code>mod_proxy_http</code> module by adding the Guard API.
  
== Configure services ==
+
===== Redhat Enterprise Linux 6 or CentOS 6 =====
  
=== Apache ===
+
<source lang="bash">$ vim /etc/httpd/conf.d/proxy_http.conf</source>
 +
===== Debian GNU/Linux 7.0 and SUSE Linux Enterprise Server 11 =====
  
Configure the mod_proxy_http module by adding the Guard API.
+
<source lang="bash">$ vim /etc/apache2/conf.d/proxy_http.conf</source>
 +
<source lang="bash"><Proxy balancer://oxguard>
 +
      Order deny,allow
 +
      Allow from all
  
'''Redhat Enterprise Linux 6 or CentOS 6'''
+
      BalancerMember http://localhost:8009/ timeout=1800 smax=0 ttl=60 retry=60 loadfactor=100 route=OX1
$ vim /etc/httpd/conf.d/proxy_http.conf
+
      ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=ON
 +
      SetEnv proxy-initial-not-pooled
 +
      SetEnv proxy-sendchunked
 +
</Proxy>
  
'''Debian GNU/Linux 7.0 and SUSE Linux Enterprise Server 11'''
+
ProxyPass /appsuite/api/oxguard balancer://oxguard/oxguard
$ vim /etc/apache2/conf.d/proxy_http.conf
+
ProxyPass /pks balancer://oxguard/pgp</source>
  
<Proxy balancer://oxguard>
+
'''Please Note''': The Guard API settings must be inserted '''''before''''' the existing <code>&lt;Proxy /appsuite/api&gt;</code> parameter.
        Order deny,allow
 
        Allow from all<br>
 
        BalancerMember http://localhost:8080/oxguard timeout=1800 smax=0 ttl=60 retry=60 loadfactor=100 route=OX1
 
        ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=ON
 
        SetEnv proxy-initial-not-pooled
 
        SetEnv proxy-sendchunked
 
</Proxy><br>
 
 
ProxyPass /appsuite/api/oxguard balancer://oxguard
 
  
'''Please Note:''' The Guard API settings must be inserted before the existing “<Proxy /appsuite/api>” parameter.
+
'''Also Note''':  If you already have a Proxy balancer for the OX backend with the same URL (say http://localhost:8080) then you don't need the second BalacnerMember entry, and you can just have the ProxyPass address that balancer instead.
  
 
After the configuration is done, restart the Apache webserver
 
After the configuration is done, restart the Apache webserver
  
$ apachectl restart
+
<source lang="bash">$ apachectl restart</source>
 
 
=== Open-Xchange ===
 
 
 
Starting in Guard 2.0, there is an administrative component to the Open-Xchange backend that notifies Guard when a user or context is deleted.  Install the package open-xchange-guard-backend-plugin on all OX backend servers.  On a debian install, this command would be:
 
 
 
apt-get install open-xchange-guard-backend-plugin
 
 
 
There is also a configuration file for the OX backend regarding some general Guard settings.  Please remove comments in front of the following settings to the configuration file guard.properties on the Open-Xchange backend servers:
 
 
 
$ vim /opt/open-xchange/etc/guard.properties
 
 
 
# OX GUard general permission, required to activate Guard in the AppSuite UI.
 
com.openexchange.capability.guard=true
 
 
# Default theme template id for all users that have no custom template id configured.
 
com.openexchange.guard.templateID=0
 
 
 
Configure the API username and password that you assigned to Guard in the server.properties file
 
  
$ vim /opt/open-xchange/etc/server.properties
+
==== Open-Xchange ====
  
# Specify the user name used for HTTP basic auth by internal REST servlet
+
Edit the <code>guard-api.properties</code> configuration file for the OX backend which contain some general Guard settings. Please remove comments in front of the following settings to the configuration file <code>guard-api.properties</code> on the Open-Xchange backend servers:
com.openexchange.rest.services.basic-auth.login=apiusername
 
 
# Specify the password used for HTTP basic auth by internal REST servlet
 
com.openexchange.rest.services.basic-auth.password=apipassword
 
  
Finally, the OX backend needs to know where the Guard server is located. This is used to notify the Guard server of changes in users, and to send emails marked for signature. The URL for the Guard server should include the url suffix /guardadmin . In the event of a cluster setup, any Guard server can be referenced here, as it is not session specific, though ideally would have a HTTP load balancer/failover URL
+
<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
 +
<source lang="bash"># OX GUard general permission, required to activate Guard in the AppSuite UI.
 +
com.openexchange.capability.guard=true
  
$ vim /opt/open-xchange/etc/guard.properties
+
# Default theme template id for all users that have no custom template id configured.
 +
com.openexchange.guard.templateID=0</source>
 +
Configure the API username and password that you assigned to Guard in the <code>server.properties</code> file:
  
# Specifies the URI to the OX Guard end-point; e.g. http://guard.host.invalid:8081/guardadmin
+
<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
# Default is empty
+
<source lang="bash"># Specify the user name used for HTTP basic auth by internal REST servlet
com.openexchange.guard.endpoint=http://guardserver:8080/guardadmin
+
com.openexchange.rest.services.basic-auth.login=apiusername
  
 +
# Specify the password used for HTTP basic auth by internal REST servlet
 +
com.openexchange.rest.services.basic-auth.password=apipassword</source>
 +
Finally, the OX backend needs to know where the Guard server is located. This is used to notify the Guard server of changes in users, and to send emails marked for signature. The URL for the Guard server should include the URL suffix <code>/guardadmin</code>. In the event of a cluster setup, any Guard server can be referenced here, as it is not session specific, though ideally would have a HTTP load balancer/failover URL:
  
 +
<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
 +
<source lang="bash"># Specifies the URI to the OX Guard end-point; e.g. http://guard.host.invalid:8081/guardadmin
 +
# Default is empty
 +
com.openexchange.guard.endpoint=http://guardserver:8009/guardadmin</source>
 
Restart the OX backend
 
Restart the OX backend
  
$ /etc/init.d/open-xchange restart
+
<source lang="bash">$ /etc/init.d/open-xchange restart</source>
 
+
==== SELinux ====
=== SELinux ===
 
 
 
Running SELinux prohibits your local Open-Xchange backend service to connect to localhost:8080, which is where the Guard backend service listens to. In order to allow localhost connections to 8080 execute the following:
 
 
 
$ setsebool -P httpd_can_network_connect 1
 
 
 
=== RHEL (Redhat) ===
 
 
 
Occasionally, the encoding of special characters in the translation files don't work properly in RHEL.  To fix this, please edit the file /opt/open-xchange/guard/etc/ox-scriptconf.sh and add to the JAVA_XTRAOPTS -DFile.encoding=UTF-8
 
 
 
  JAVA_XTRAOPTS="-Xmx1024m -Dfile.encoding=UTF-8"
 
  
== Initiating the Guard database and key store ==
+
Running SELinux prohibits your local Open-Xchange backend service to connect to localhost:8009, which is where the Guard backend service listens to. In order to allow localhost connections to 8009 execute the following:
  
Once the Guard configuration (database and backend configuration) and the service configuration has been applied, the Guard administration script needs to be executed in order to create the Guard databases. The administration script also takes care of the creation of the master keys and the master password file in /opt/open-xchange/guard. The initiation only needs to be done once for a multi server setup, for details please see “Optional / Clustering”.
+
<source lang="bash">$ setsebool -P httpd_can_network_connect 1</source>
 +
=== Generating the <code>oxguardpass</code> ===
  
'''Please Note:''' If you run a cluster of OX / Guard nodes, only execute this command on ONE node. Not on all nodes!  See [[AppSuite:GuardCluster | Ox Guard Clustering]] for details.
+
Once the Guard configuration (database and backend configuration) and the service configuration has been applied, the Guard administration script needs to be executed in order to create the master password file in <code>/opt/open-xchange/etc/oxguardpass</code>. The initiation only needs to be done '''once''' for a multi server setup, for details please see the sections '''Optional''' and/or '''Clustering'''.
  
/opt/open-xchange/guard/sbin/guard init
+
'''Please Note''': If you run a cluster of OX / Guard nodes, only execute this command on '''ONE''' node. Not on all nodes! See [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering] for details.
  
'''Please Note:''' It is important to understand that the master password file located at /opt/open-xchange/guard/oxguardpass is required to reset user passwords, without them the administrator will not be able to reset user passwords anymore in the future. The file contains the passwords used to encrypt the master database key, as well as passwords used to encrypt protected data in the users table. It must be the same on all Guard servers.
+
<source lang="bash">$ /opt/open-xchange/sbin/guard --init</source>
 +
'''Please Note''': It is important to understand that the master password file located at <code>/opt/open-xchange/etc/oxguardpass</code> is required to reset user passwords; without them the administrator will not be able to reset user passwords anymore in the future. The file contains the passwords used to encrypt the master database key, as well as passwords used to encrypt protected data in the users table. It must be the same on all Guard servers.
  
== Test Setup ==
+
=== Test Setup ===
  
Not required, but it is a good idea to test the Guard setup before starting the initialization. The test function will verify that Guard has a good connection to the OX backend, and that it can resolve email addresses to users.
+
Not required, but it is a good idea to test the Guard setup before starting the initialization. The test function will verify that Guard has a good connection to the OX backend, and that it can resolve email addresses to users.
  
 
To test, use an email address that exists on the OX backend (john@example.com for this example)
 
To test, use an email address that exists on the OX backend (john@example.com for this example)
  
/opt/open-xchange/guard/sbin/guard test john@example.com
+
<source lang="bash">/opt/open-xchange/sbin/guard --test john@example.com</source>
 
+
Guard should return information from the OX backend regarding the user associated with &quot;john@example.com&quot;. Problems resolving information for the user should be resolved before using Guard. Check Rest API passwords and settings if errors returned.
Guard should return information from the OX backend regarding the user associated with john@example.com. Problems resolving information for the user should be resolved before using Guard. Check Rest API passwords and settings if errors returned.
 
 
 
 
 
== Start Guard ==
 
  
The services have been configured and the database has been initiated, it's time to start Guard
+
=== Enabling Guard for Users ===
  
$ /etc/init.d/open-xchange-guard start
+
Guard provides two capabilities for users in the environment as well as a basic &quot;core&quot; level:
  
== Enabling Guard for Users ==
+
* Guard: <code>com.openexchange.capability.guard</code>
 +
* Guard Mail: <code>com.openexchange.capability.guard-mail</code>
 +
* Guard Drive: <code>com.openexchange.capability.guard-drive</code>
 +
* Guard Documents: <code>com.openexchange.capability.guard-docs</code>
  
Guard provides two capabilities for users in the environment as well as a basic "core" level:
+
The &quot;core&quot; Guard enabled a basic read functionality for Guard encrypted emails. We recommend enabling this for all users, as this allows all recipients to read Guard emails sent to them. Great opportunity for upsell. Recipients with only Guard enabled can then do a secure reply to the sender, but they can't start a new email or add recipients.
  
* '''Guard:''' com.openexchange.capability.guard
+
'''Guard Mail''', '''Guard Drive''', and '''Guard Documents''' are additional options for users. &quot;Guard Mail&quot; allows users the full functionality of Guard emails. &quot;Guard Drive&quot; allows for encryption and decryption of drive files. &quot;Guard Documents&quot; enable encryption capabilitiy to office documents.
* '''Guard Mail:''' com.openexchange.capability.guard-mail
 
* '''Guard Drive:''' com.openexchange.capability.guard-drive
 
  
The "core" Guard enabled a basic read functionality for Guard encrypted emails. We recommend enabling this for all users, as this allows all recipients to read Guard emails sent to them. Great opportunity for upsell.  Recipients with only Guard enabled can then do a secure reply to the sender, but they can't start a new email or add recipients.
+
Each of the Guard components is enabled for all users that have the according capability configured. Please note that users need to have the Drive permission set to use Guard Drive. So the users that have Guard Drive enabled must be a subset of those users with OX Drive permission. Since v7.6.0 we enforce this via the default configuration. Those capabilities can be activated for specific user by using the Open-Xchange provisioning scripts:
  
"Guard Mail" and "Guard Drive" are additional options for users.  "Guard Mail" allows users the full functionality of Guard emails.  "Guard Drive" allows for encryption and decryption of drive files.
+
==== Guard Mail: ====
  
Each of those two Guard components is enabled for all users that have the according capability configured. Please note that users need to have the Drive permission set to use Guard Drive. So the users that have Guard Drive enabled must be a subset of those users with OX Drive permission. Since v7.6.0 we enforce this via the default configuration. Those capabilities can be activated for specific user by using the Open-Xchange provisioning scripts:
+
<source lang="bash">$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-mail=true</source>
 +
==== Guard Drive: ====
  
'''Guard Mail:'''
+
<source lang="bash">$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-drive=true</source>
$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-mail=true
 
  
'''Guard Drive:'''
+
==== Guard Documents: ====
$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-drive=true
 
  
'''Please Note:''' Guard Drive requires Guard Mail to be configured for the user as well. In addition, these capabilities may be configured globally by editing the guard.properties file on the OX bakend
+
<source lang="bash">$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-docs=true</source>
  
== Optional ==
+
'''Please Note''': Guard Drive requires Guard Mail to be configured for the user as well. In addition, these capabilities may be configured globally by editing the <code>guard-api.properties</code> file on the OX bakend.
  
=== SSL Configuration ===
+
=== Recipient key detection ===
  
Per default the connection between the Guard backend and the configured Open-Xchange REST API host is unencrypted. Even though that Guard will never transmit unencrypted emails to or from the REST API you can optionally encrypt the whole communication between those two components by using SSL. To enforce Guard to use SSL in the communication between those two components enable the follwing configuration in Guard configuration file.
+
==== Local ====
  
  $ vim /opt/open-xchange/guard/etc/guard.properties
+
Guard needs to determine if an email recipients email address is an internal or external (non-ox) user.
  
  com.openexchange.guard.backend_ssl=true
+
To detect if the recipient is an account on the same OX Guard system there is a mechanism needed to map a recipient mail address to the correct local OX context. The default implementation delivered in the product achieves that by looking up the mail domain (@example.com) within the list of context mappings. That is at least not possible in case of ISPs where different users/contexts use the same mail domain. In case your OX system does not use mail domains in context mappings it is required to deploy an OX OSGi bundle implementing the <code>com.openexchange.mailmapping.MailResolver</code> class or by interfacing Guard with your mail resolver system. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver OX Guard Mail Resolver] for details.
  
The Guard backend is most commonly placed behind a load balancer (APACHE or other) and defaults to HTTP for incoming and outgoing traffic, using the load balancer to do SSL with the users.  If you want Guard to use SSL for all communications, you need to set up the SSL key to use.
+
==== External ====
  
Please note that you have to provide access to the certificates.
+
Starting with Guard 2.0, Guard will use public PGP Key servers if configured to find PGP Public keys. In addition, Guard will also look up SRV records for PGP Key servers for a recipients domain. This follows the standards [http://tools.ietf.org/html/draft-shaw-openpgp-hkp-00#page-9 OpenPGP Draft].
 
 
com.openexchange.guard.useSSL: true
 
com.openexchange.guard.SSLPort: 8443
 
com.openexchange.guard.SSLKeyStore: //keystore location//
 
com.openexchange.guard.SSLKeyName: //alias name here//
 
com.openexchange.guard.SSLKeyPass: //ssl password//
 
 
 
'''Please Note:''' Enabling SSL might decrease performance and/or create more system load due to additional encoding of the HTTP streams.
 
 
 
For details on SSL installation and configuration, please see [[AppSuite:GuardSSL|OX Guard SSL Installation]]
 
 
 
== Recipient key detection ==
 
 
 
=== Local ===
 
 
 
Guard needs to determine if an email recipients email address is an internal or external (non-ox) user. 
 
 
 
To detect if the recipient is an account on the same OX Guard system there is a mechanism needed to map a recipient mail address to the correct local OX context. The default implementation delivered in the product achieves that by looking up the mail domain (@example.com) within the list of context mappings. That is at least not possible in case of ISPs where different users/contexts use the same mail domain. In case your OX system does not use mail domains in context mappings it is required to deploy an OX OSGi bundle implementing the com.openexchange.mailmapping.MailResolver class or by interfacing Guard with your mail resolver system.
 
Please see [[Appsuite:GuardMailResolver|OX Guard Mail Resolver]] for details
 
 
 
=== External ===
 
 
 
Starting with Guard 2.0, Guard will use public PGP Key servers if configured to find PGP Public keys. In addition, Guard will also look up SRV records for PGP Key servers for a recipients domain. This follows the standards [http://tools.ietf.org/html/draft-shaw-openpgp-hkp-00#page-9 OpenPGP Draft].
 
  
 
External PGP servers to use can be configured in the guard.properties file on the Guard servers.
 
External PGP servers to use can be configured in the guard.properties file on the Guard servers.
  
com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371
+
<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source>
 
+
If you would like this Guard installation discoverable by other Guard servers, then create an SRV record for each domain (&quot;example.com&quot; in this illustration):
If you would like this Guard installation discoverable by other Guard servers, then create a SRV record for each domain ("example.com" in this illustration)
 
 
_hkp._tcp.open-xchange.com. 28800 IN    SRV    10 1 80 appsuite.example.com.
 
 
 
You will also need to make additional entries in the apache proxy_http.conf file.
 
 
 
<Proxy balancer://oxguardpgp>
 
        Order deny,allow
 
        Allow from all, add
 
        BalancerMember http://guardserver:8080/pgp timeout=1800 smax=0 ttl=60 retry=60 loadfactor=50 route=OX3
 
        ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=ON
 
        SetEnv proxy-initial-not-pooled
 
        SetEnv proxy-sendchunked
 
  </Proxy>
 
  
<Proxy /pks>
+
<source lang="bash">_hkp._tcp.open-xchange.com. 28800 IN    SRV    10 1 80 appsuite.example.com.</source>
        ProxyPass balancer://oxguardpgp
 
</Proxy>
 
  
'''Please Note''' PGP Public key servers by default append use the url server/pks when the record is obtained from a SRV record. The proxy above routes anything with the apache domain/pks to the Oxguard PGP server
+
'''Please Note''' PGP Public key servers by default append use the URL server/pks when the record is obtained from an SRV record. The proxy above routes anything with the Apache domain/pks to the OX Guard PGP server.
  
== Clustering ==
+
=== Clustering ===
  
 
You can run multiple OX Guard servers in your environment to ensure high availability or enhance scalability. OX Guard integrates seamlessly into the existing Open-Xchange infrastructure by using the existing interface standards and is therefor transparent to the environment. A couple of things have to be prepared in order to loosely couple OX Guard servers with Open-Xchange servers in a cluster.
 
You can run multiple OX Guard servers in your environment to ensure high availability or enhance scalability. OX Guard integrates seamlessly into the existing Open-Xchange infrastructure by using the existing interface standards and is therefor transparent to the environment. A couple of things have to be prepared in order to loosely couple OX Guard servers with Open-Xchange servers in a cluster.
  
=== MySQL ===
+
==== MySQL ====
  
The MySQL servers need to be configured in order to allow access to the configdb of Open-Xchange. To do so you need to set the following configuration in the MySQL my.cnf:
+
The MySQL servers need to be configured in order to allow access to the configdb of Open-Xchange. To do so you need to set the following configuration in the MySQL <code>my.cnf</code>:
  
bind = 0.0.0.0
+
<source lang="bash">bind = 0.0.0.0</source>
 +
This allows the Guard backend to bind to the MySQL host which is configured in the <code>guard-core.properties</code> file with <code>com.openexchange.guard.configdbHostname</code>. After the bind for the MySQL instance is configured and the OX Guard backend would be able to connect to the configured host, you have to grant access for the OX Guard service on the MySQL instance to manage the databases. Do so by connecting to the MySQL server via the MySQL client. Authenticate if necessary and execute the following, please note that you have to modify the hostname / IP address of the client who should be able to connect to this database, it should include all possible OX Guard servers:
  
This allows the Guard backend to bind to the MySQL host which is configured in the guard.properties file with com.openexchange.guard.configdbHostname. After the bind for the MySQL instance is configured and the OX Guard backend would be able to connect to the configured host, you have to grant access for the OX Guard service on the MySQL instance to manage the databases. Do so by connecting to the MySQL server via the mysql client. Authenticate if necessary and execute the following, please note that you have to modify the hostname / IP address of the client who should be able to connect to this database, it should include all possible OX Guard servers:
+
<source lang="sql">GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;</source>
  
GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;
+
==== Apache ====
  
=== Apache ===
+
OX Guard uses the Open-Xchange REST API to store and fetch data from the Open-Xchange databases. The REST API is a servlet running in the Grizzly container. By default it is not exposed as a servlet through Apache and is only accessibly via port 8009. In order to use Apache's load balancing via <code>mod_proxy</code> we need to add a servlet called &quot;preliminary&quot; to <code>proxy_http.conf</code>, example based on a clustered <code>mod_proxy</code>configuration:
  
OX Guard uses the Open-Xchange REST API to store and fetch data from the Open-Xchange databases. The REST API is a servlet running in the Grizzly container. By default it is not exposed as a servlet through Apache and is only accessibly via port 8009. In order to use Apache's load balancing via mod_proxy we need to add a servlet called "preliminary" to proxy_http.conf, example based on a clustered mod_proxy configuration:
+
<source lang="bash"><Location /preliminary>
 +
    Order Deny,Allow
 +
    Deny from all
 +
    # Only allow access from Guard servers within the network. Do not expose this
 +
    # location outside of your network. In case you use a load balancing service in front
 +
    # of your Apache infrastructure you should make sure that access to /preliminary will
 +
    # be blocked from the Internet / outside clients. Examples:
 +
    # Allow from 192.168.0.1
 +
    # Allow from 192.168.1.1 192.168.1.2
 +
    # Allow from 192.168.0.
 +
</Location>
  
<Location /preliminary>
+
ProxyPass /preliminary balancer://oxcluster/preliminary
      Order Deny,Allow
+
</source>
      Deny from all
 
      # Only allow access from Guard servers within the network. Do not expose this
 
      # location outside of your network. In case you use a load balancing service in front
 
      # of your Apache infrastructure you should make sure that access to /preliminary will
 
      # be blocked from the internet / outside clients. Examples:
 
      # Allow from 192.168.0.1
 
      # Allow from 192.168.1.1 192.168.1.2
 
      # Allow from 192.168.0.
 
      ProxyPass /preliminary balancer://oxcluster/preliminary
 
</Location>
 
  
Make sure that the balancer is properly configured in the mod_proxy configuration. Examples on how to do so can be found in our clustering configuration for Open-Xchange AppSuite. Like explained in the example above, please make sure that this location is only available in your internal network, there is no need to expose /preliminary to the public, it is only used by Guard servers to connect to the OX backend. If you have a load balancer in front of the Apache cluster you should consider blocking access to /preliminary from WAN to restrict access to the servlet to internal network services only.
+
Make sure that the balancer is properly configured in the <code>mod_proxy</code> configuration. Examples on how to do so can be found in our clustering configuration for Open-Xchange AppSuite. Like explained in the example above, please make sure that this location is only available in your internal network, there is no need to expose <code>/preliminary</code> to the public, it is only used by Guard servers to connect to the OX backend. If you have a load balancer in front of the Apache cluster you should consider blocking access to <code>/preliminary</code> from WAN to restrict access to the servlet to internal network services only.
  
Now add the OX Guard BalancerMembers to the oxguard balancer configuration (also in proxy_http.conf) to address all your OX Guard nodes in the cluster in this balancer configuration. The configuration has to be applied to all Apache nodes within the cluster.
+
Now add the OX Guard <code>BalancerMembers</code> to the oxguard balancer configuration (also in <code>proxy_http.conf</code>) to address all your OX Guard nodes in the cluster in this balancer configuration. The configuration has to be applied to all Apache nodes within the cluster.
  
If the Apache server is a dedicated server / instance you also have to install the OX Guard UI-Static package on all Apache nodes in the cluster in order to provide static files like images or CSS to the OX Guard client. Example for Debian (the OX Guard repository has to be configured in the package management prior):
+
If the Apache server is a dedicated server <code>/</code> instance you also have to install the OX Guard UI-Static package on all Apache nodes in the cluster in order to provide static files like images or CSS to the OX Guard client. Example for Debian (the OX Guard repository has to be configured in the package management prior):
  
$ apt-get install open-xchange-guard-ui-static
+
<source lang="bash">$ apt-get install open-xchange-guard-ui-static</source>
  
=== Open-Xchange ===
+
==== Open-Xchange ====
  
 
Disable the Open-Xchange IPCheck for session verification. This is required because OX Guard will use the users session cookie to connect to the Open-Xchange REST API, but as a different IP address than the OX Guard server has been used during authentication the request would fail if you don't disable the IPCheck:
 
Disable the Open-Xchange IPCheck for session verification. This is required because OX Guard will use the users session cookie to connect to the Open-Xchange REST API, but as a different IP address than the OX Guard server has been used during authentication the request would fail if you don't disable the IPCheck:
  
$ vim /opt/open-xchange/etc/server.properties
+
<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
 
 
 
and set:
 
and set:
  
com.openexchange.IPCheck=false
+
<source lang="bash">com.openexchange.IPCheck=false</source>
 
 
 
The OX Guard UI package has to be installed on all Open-Xchange backend nodes as well, example for Debian (the OX Guard repository has to be configured in the package management prior):
 
The OX Guard UI package has to be installed on all Open-Xchange backend nodes as well, example for Debian (the OX Guard repository has to be configured in the package management prior):
  
$ apt-get install open-xchange-guard-ui
+
<source lang="bash">$ apt-get install open-xchange-guard-ui</source>
 
 
 
Restart the Open-Xchange service afterwards.
 
Restart the Open-Xchange service afterwards.
  
=== OX Guard ===
+
==== OX Guard ====
 
 
For details in clustering Guard servers, please see [[AppSuite:GuardCluster | OxGuard Clustering]] .  It is critical that all Guard servers have the same oxguardpass file.  Please see the clustering link for details.  Do not run ./guard init on more than one server.
 
  
After all the services like MySQL, Apache and Open-Xchange have been configured you need to update the OX Guard backend configuration to point to the correct API endpoints. Set the REST API endpoint to an Apache server by setting the following value in /opt/open-xchange/guard/etc/guard.properties:
+
For details in clustering Guard servers, please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering]. It is '''critical''' that all Guard servers have the same <code>oxguardpass</code> file. Please see the clustering link for details. Do not run <code>/opt/open-xchange/sbin/guard --init</code> on more than one server.
  
com.openexchange.guard.restApiHostname=apache.example.com
+
After all the services like MySQL, Apache and Open-Xchange have been configured you need to update the OX Guard backend configuration to point to the correct API endpoints. Set the REST API endpoint to an Apache server by setting the following value in <code>/opt/open-xchange/etc/guard-core.properties</code>:
  
Per default Guard will try to connect to port 8009 to this host, but as we configured the REST API to be proxies thorugh the serblet /preliminary on every Apache we now also need to change the target port for the REST API. You can do so by adding the following line into /opt/open-xchange/guard/etc/guard.properties:
+
<source lang="bash">com.openexchange.guard.restApiHostname=apache.example.com</source>
 +
Per default Guard will try to connect to port 8009 to this host, but as we configured the REST API to be proxies thorugh the servlet <code>/preliminary</code> on every Apache we now also need to change the target port for the REST API. You can do so by adding the following line into <code>/opt/open-xchange/etc/guard-core.properties</code>:
  
com.openexchange.guard.oxBackendPort=80
+
<source lang="bash">com.openexchange.guard.oxBackendPort=80</source>
 +
Please also change all settings in regards to MySQL like <code>com.openexchange.guard.configdbHostname</code>, <code>com.openexchange.guard.oxguardDatabaseHostname</code>, <code>com.openexchange.guard.databaseUsername</code> or <code>om.openexchange.guard.databasePassword</code>.
  
Please also change all settings in regards to MySQL like com.openexchange.guard.configdbHostname, com.openexchange.guard.oxguardDatabaseHostname, com.openexchange.guard.databaseUsername or com.openexchange.guard.databasePassword. Afterwards restart the OX Guard service and check the logfile if the OX Guard backend is able to connect to the configured REST API.
+
Afterwards restart the OX Guard service and check the log file if the OX Guard backend is able to connect to the configured REST API.
  
== Multi Node ==
+
=== Multi Node ===
  
If you have multiple OX and Guard installations, please see the following documentation [[AppSuite:OX_Guard_Modular|OX Guard Modular Setup]]
+
If you have multiple OX and Guard installations, please see the following documentation [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Modular OX Guard Modular Setup].
  
= Support API =
+
== Support API ==
  
The OX Guard Support API enables administrative access to various functions for maintaining OX Guard from a client in a role as a support employee. A client has to do a BASIC AUTH authentication in order to access the API. Username and password can be configured in the guard.properties file using the following settings:
+
The OX Guard Support API enables administrative access to various functions for maintaining OX Guard from a client in a role as a support employee. A client has to do a BASIC AUTH authentication in order to access the API. Username and password can be configured in the guard-core.properties file using the following settings:
  
<code>
+
<source lang="bash"># Specify the username and password for accessing the Support API of Guard
    # Specify the username and password for accessing the Support API of Guard
+
com.openexchange.guard.supportApiUsername=
    com.openexchange.guard.supportapiusername=
+
com.openexchange.guard.supportApiPassword=</source>
    com.openexchange.guard.supportapipassword=
+
In contrast to the rest of the OX Guard requests, the OX Guard support API requests are accessible using: /guardsupport. This distinction allows more flexible configuration since the support API should not always be accessible from everywhere.
</code>
 
  
In contrast to the rest of the OX Guard requests, the OX Guard support API requests are accessible using: /guardsupport. This distinction allows more flexible configuration since the support API should not always be accessible from everywhere. But if you want to expose the Guard Support API using Apache a very basic Apache configuration could look like this:
+
'''Warning''': Exposing the support API to the internet could be huge security risk. Only add to Apache if you know what you are doing.
  
'''Warning''' Exposing the support API to the internet could be huge security risk.  Only add to apache if you know what you are doing
 
 
<code>
 
  <Location /appsuite/api/guardsupport>                                                             
 
        ProxyPass http://localhost:8080/guardsupport                                                   
 
        #...
 
  </Location>     
 
</code>
 
 
it might also be preferable to add a new balancer directive for guardsupport
 
<code>
 
<Location /appsuite/api/guardsupport>                                                             
 
        ProxyPass balancer://oxguardsupport                                                         
 
</Location>
 
<Proxy balancer://oxguardsupport>                                                               
 
      #...
 
        BalancerMember http://localhost:8080/guardsupport #...
 
      #...
 
</Proxy>
 
</code>
 
  
 
=== Reset password ===
 
=== Reset password ===
POST <code>/guardsupport/?action=reset_password</code>
 
  
Performs a password reset and sends a new random generated password to a specified email address by the user or a default address if the user did not specify an email address. The reset password function is currently not available for guest users.
+
<code>POST /guardsupport/?action=reset_password</code>
  
Since Guard 2.0
+
Performs a password reset and sends a new random generated password to a specified email address by the user or a default address if the user did not specify an email address. (''Since Guard 2.0'')
  
 
Parameters:
 
Parameters:
 +
 
* <code>email</code> – The email address of the user to reset the password for
 
* <code>email</code> – The email address of the user to reset the password for
 
* <code>default</code> (optional) – The email address to send the new password to, if the user did not specify a secondary email address
 
* <code>default</code> (optional) – The email address to send the new password to, if the user did not specify a secondary email address
 +
 +
Response:
 +
PRIMARY if the reset was sent to the primary email address.  SECONDARY if the reset email was sent to the secondary email address that the user specified
  
 
=== Expose key ===
 
=== Expose key ===
  
POST <code>/guardsupport/?action=expose_key</code>
+
<code>POST /guardsupport/?action=expose_key</code>
  
Marks a deleted user key temporary as “exposed” and creates a unique URL for downloading the exposed key.
+
Marks a deleted user key temporary as “exposed” and creates a unique URL for downloading the exposed key. Automatic resetting of exposed keys to &quot;not exposed&quot; is scheduled once a day and resets all exposed keys which have been exposed before X hours, where X can be configured using com.openexchange.guard.exposedKeyDurationInHours in the guard.properties files. (''Since Guard 2.0'')
Automatic resetting of exposed keys to "not exposed" is scheduled once a day and resets all exposed keys which have been exposed before X hours, where X can be configured using com.openexchange.guard.exposedKeyDurationInHours in the guard.properties files.
 
  
Since Guard 2.0
+
Parameters:
  
Parameters:
 
 
* <code>email</code> – The email address of the user to expose the deleted keys for
 
* <code>email</code> – The email address of the user to expose the deleted keys for
 
* <code>cid</code> – The context id
 
* <code>cid</code> – The context id
  
Response:
+
Response: A URL pointing to the downloadable exposed keys.
An URL pointing to the downloadable exposed keys
 
  
 
=== Delete user ===
 
=== Delete user ===
  
POST <code>/guardsupport/?action=delete_user</code>
+
<code>POST /guardsupport/?action=delete_user</code>
  
Deletes all keys related to a certain user. The keys are backed up and can be exposed using the “expose_key” call.
+
Deletes all keys related to a certain user. The keys are backed up and can be exposed using the “expose_key” call. (''Since Guard 2.0'')
  
Since Guard 2.0
+
Parameters:
  
Parameters:
 
 
* <code>user_id</code> – The user's id
 
* <code>user_id</code> – The user's id
 
* <code>cid</code> - The context id
 
* <code>cid</code> - The context id
  
= Customization =
+
=== Upgrade User (Release 2.10 and later) ===
 +
 
 +
<code>POST /guardsupport/?action=upgrade_guest</code>
 +
 
 +
Upgrades a Guest account.  This action copies all of the keys from the Guest account to a full OX account, assuming that user has Guard capabilities.
 +
 
 +
Parameters:
 +
 
 +
* <code>email</code> - The email address of the Guest user
 +
* <code>user_id</code> – The user's new id
 +
* <code>cid</code> - The user's new context id
 +
 
 +
== Customisation ==
  
Guard's templates are customizable at the user and context level. Please see [[AppSuite:GuardCustomization| Customization]] for details
+
Guard's templates are customisable at the user and context level. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization Customisation] for details.
  
= Entropy =
+
== Entropy ==
  
Guard requires entropy (randomness) to generate the private/public keys that are used. Depending on the server and it's environment, this may become a problem. Please see [[AppSuite:GuardEntropy | Entropy]] for a possible solution
+
Guard requires entropy (randomness) to generate the private/public keys that are used. Depending on the server and it's environment, this may become a problem. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardEntropy Entropy] for a possible solution.

Revision as of 17:13, 8 July 2019

Contents

OX Guard (Version 2.4 - 2.8)

For previous versions of OX Guard, please click here

If upgrading from 2.0 or 2.2, please see the following article

Overview

OX Guard is a fully integrated security add-on to OX App Suite that provides end users with a flexible email and file encryption solution. OX Guard is a highly scalable, multi server, feature rich solution that is so simple-to-use that end users will actually use it. With a single click a user can take control of their security and send secure emails and share encrypted files. This can be done from any device to both OX App Suite and non-OX App Suite users.

OX Guard uses standard PGP encryption for the encryption of email and files. PGP has been around for a long time, yet has not really caught on with the masses. This is generally blamed on the confusion and complications of managing the keys, understanding trust, PGP format types, and lack of trusted central key repositories. Guard simplifies all of this, making PGP encryption as easy as a one click process, with no keys to keep track of, yet the options of advanced PGP management for those that know how.

This article will guide you through the installation of Guard and describes the basic configuration and software requirements. As it is intended as a quick walk-through it assumes an existing installation of the operating system including a single server App Suite setup as well as average system administration skills. This guide will also show you how to setup a basic installation with none of the typically used distributed environment settings. The objective of this guide is:

  • To setup a single server installation
  • To setup a single Guard instance on an existing Open-Xchange installation, no cluster
  • To use the database service on the existing Open-Xchange installation for Guard, no replication
  • To provide a basic configuration setup, no mail server configuration

Key Features

  • Simple security at the touch of a button
  • Provides user based security - Separate from provider
  • Supplementary security to Provider based security - Layered
  • Powerful features yet simple to use and understand
  • Security - Inside and outside of the OX environment
  • Email and Drive integration
  • Uses proven PGP security

Availability

If an OX App Suite customer would like to evaluate OX Guard integration, the first step is to contact OX Sales. OX Sales will then work on the request and send prices and license/API (for the hosted infrastructure) key details to the customer.

Requirements

Please review OX Guard Requirements for a full list of requirements.

Since OX Guard is a Microservice it can either be added to an existing Open-Xchange installation or it can be deployed on a dedicated environment. OX App Suite v7.8.1 or later is required to operate this extension both in a single or multi server environments.

Prerequisites

  • Open-Xchange REST API
  • Grizzly HTTP connector (open-xchange-grizzly)
  • A supported Java Virtual Machine (Java 7)
  • An Open-Xchange App Suite installation v7.8.1 or later
  • Please Note: To get access to the latest minor features and bug fixes, you need to have a valid license. The article Updating OX-Packages explains how that can be done.

Version Matrix

Core Version Guard Version
7.8.1 2.4.0 or 2.4.2
7.8.2 2.4.2
7.8.3 2.6.0
7.8.4 2.8.0
7.10.0 2.10.0
7.10.1 2.10.1
7.10.2 2.10.2

Important Notes

Customisation

OX Guard version supports branding / theming using the configuration cascade, defining a templateID for a user or context. Check the OX Guard Customisation article for more details.

Mail Resolver

READ THIS VERY CAREFULLY; BEFORE PROCEEDING WITH GUARD INSTALLATION!

The Guard installation must be able to determine if an email recipient is a local OX user or if it should be a guest account. The default MailResolver uses the context domain name to do this. On many installations, domains may extend across multiple context and multiple database shards. In these cases, the default MailResolver won't work. In addition, if a custom authentication package is used, the Mail Resolver will likely not work.

Once Guard is installed, please be sure to test the mail resolver using:

/opt/open-xchange/sbin/guard test email@domain

to see if the mail Resolver works.

If the test does not work, you will likely need a custom Mail Resolver. Please see Mail Resolver page

This resolver software depends heavily on your local deployment.

Download and Installation

General

The installation of the open-xchange-guard-backend-plugin package which is required for Guard and the main open-xchange-guard package in version 2.4.0 or higher will eventually execute database update tasks if installed and activated. Please take this into account.

There are several components to the Guard service. They can be all installed on the same server as the OX middleware or on a separate server.

The components required for the OX middleware are: open-xchange-rest, open-xchange-guard-backend-plugin and open-xchange-guard-ui.

The components required for the OX frontend are: open-xchange-guard-ui-static open-xchange-guard-reader and optionally open-xchange-guard-help-en-us (or preferred language for help files).

The components required for the Guard server open-xchange-guard and either open-xchange-guard-file-storage or open-xchange-guard-s3-storage depending on what storage you want to use. The examples below make use of the open-xchange-guard-file-storage. Adjust the commands accordingly to fit your needs. In addition open-xchange and open-xchange-core are required to run OX Guard.

Debian Linux 8.0 (Jessie)

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/guard/stable/guard/DebianJessie /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>

and then run for a single node installation:

$ apt-get update
$ apt-get install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin open-xchange-guard-reader</source>

or the following for a distributed installation:

$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage</source>

The packages open-xchange-guard-ui open-xchange-rest and open-xchange-guard-backend-plugin missing in the distributed installation have to be installed on the node running the middleware. The packages open-xchange-guard-ui-static and open-xchange-guard-reader must be installed in the frontend (apache node).

RedHat Enterprise Linux 6 or CentOS 6

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard]
name=Open-Xchange-guard-stable-guard
baseurl=https://software.open-xchange.com/products/guard/stable/guard/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m
[ox-backend]
name=Open-Xchange-backend
baseurl=https://software.open-xchange.com/products/appsuite/stable/backend/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>

and then run for a single node installation:

$ yum update
$ yum install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin open-xchange-guard-reader</source>

or the following for a distributed installation:

$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage</source>

The packages open-xchange-guard-ui open-xchange-rest and open-xchange-guard-backend-plugin missing in the distributed installation have to be installed on the node running the middleware. The packages open-xchange-guard-ui-static and open-xchange-guard-reader must be installed in the frontend (apache node).

Redhat Enterprise Linux 7 or CentOS 7

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard]
name=Open-Xchange-guard-stable-guard
baseurl=https://software.open-xchange.com/products/guard/stable/guard/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m
[ox-backend]
name=Open-Xchange-backend
baseurl=https://software.open-xchange.com/products/appsuite/stable/backend/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>

and then run for a single node installation:

$ yum update
$ yum install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin open-xchange-guard-reader</source>

or the following for a distributed installation:

$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage</source>

The packages open-xchange-guard-ui open-xchange-rest and open-xchange-guard-backend-plugin missing in the distributed installation have to be installed on the node running the middleware. The packages open-xchange-guard-ui-static and open-xchange-guard-reader must be installed in the frontend (apache node).

SUSE Linux Enterprise Server 11 (valid until v2.4.2)

Add the package repository using zypper if not already present:

$ zypper ar https://software.open-xchange.com/products/guard/2.4.2/guard/SLES11 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/7.8.2/backend/SLES11 ox-backend</source>

and then run for a single node installation:

$ zypper ref
$ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin open-xchange-guard-reader</source>

or the following for a distributed installation:

$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage</source>

The packages open-xchange-guard-ui open-xchange-rest and open-xchange-guard-backend-plugin missing in the distributed installation have to be installed on the node running the middleware. The packages open-xchange-guard-ui-static and open-xchange-guard-reader must be installed in the frontend (apache node).

SUSE Linux Enterprise Server 12

Add the package repository using zypper if not already present:

$ zypper ar https://software.open-xchange.com/products/guard/stable/guard/SLE_12 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLE_12 ox-backend</source>

and then run for a single node installation:

$ zypper ref
$ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-reader</source>

or the following for a distributed installation:

$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage</source>

The packages open-xchange-guard-ui open-xchange-rest and open-xchange-guard-backend-plugin missing in the distributed installation have to be installed on the node running the middleware. The packages open-xchange-guard-ui-static and open-xchange-guard-reader must be installed in the frontend (apache node).


Univention Corporate Server

If you have purchased the OX App Suite for UCS, the OX Guard is part of the offering. OX Guard is available in the Univention App Center. Please check the UMC module App Center for the installation of the OX Guard at your already available environment.

Please note: By default, OX Guard generates the link to the secure content for external recipients on the basis of the local fully qualified domain name (FQDN). If the local FQDN is not reachable from the Internet, it has to be specified manually. This can be done by setting a UCR variable, e.g. via the UMC module "Univention Configuration Registry". The variable has to contain the external FQDN of the OX Guard system:

oxguard/cfg/guard.properties/com.openexchange.guard.externalEmailURL=HOSTNAME.DOMAINNAME

Update OX Guard

This section contains information about updating a 2.4.0 version (e.g. for patch fixes). Upgrading from prior versions is discussed in different articles. You can find more information in the Update OX Guard Versions <= 2.2.x and Update OX Guard Versions <= 2.0.x sections below.

Debian Linux 7.0 (Wheezy) (valid until v2.4.2)

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/2.4.2/guard/updates/DebianWheezy /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/7.8.2/backend/DebianWheezy /</source>

Then run:

$ apt-get update
$ apt-get dist-upgrade</source>

If you want to see, what apt-get is going to do without actually doing it, you can run:

$ apt-get dist-upgrade -s</source>

Debian Linux 8.0 (Jessie)

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianJessie /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>

Then run:

$ apt-get update
$ apt-get dist-upgrade</source>

If you want to see, what apt-get is going to do without actually doing it, you can run:

$ apt-get dist-upgrade -s</source>

Redhat Enterprise Linux 6 or CentOS 6

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard-updates]
name=Open-Xchange-guard-stable-guard-updates
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m
[ox-backend]
name=Open-Xchange-backend
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>

and then run:

$ yum update
$ yum upgrade</source>

Redhat Enterprise Linux 7 or CentOS 7

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard-updates]
name=Open-Xchange-guard-stable-guard-updates
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m
[ox-backend]
name=Open-Xchange-backend
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>

and then run:

$ yum update
$ yum upgrade</source>


SUSE Linux Enterprise Server 12

Add the package repository using zypper if not already present:

$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/SLE_12 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLE_12 ox-backend</source>

and then run:

$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>

You might need to run:

$ zypper ref</source>

to update the repository metadata before running zypper up.

Univention Corporate Server

If you have purchased the OX App Suite for UCS, the OX Guard is part of the offering. OX Guard is available in the Univention App Center. Please check the UMC module App Center for the update of the OX Guard.

Update OX Guard Versions <= 2.2.x

If you are upgrading from a 2.2 version to 2.4, please read the Upgrading from 2.0 or 2.2 to 2.4 article.

Configuration

The following gives an overview of the most important settings to enable Guard for users on the Open-Xchange installation. Some of those settings have to be modified in order to establish the database and REST API access from the Guard service. All settings relating to the Guard backend component are located in the configuration file guard-core.properties located in /opt/open-xchange/etc. The default configuration should be sufficient for a basic "up-and-running" setup (with the exception of defining the database username and password). Please refer to the inline documentation of the configuration file for more advanced options. Additional information can be found in the Guard Configuration article.

Basic Configuration

$ vim /opt/open-xchange/etc/guard-core.properties

Guard database for storing Guard user information, main lookup tables:

com.openexchange.guard.oxguardDatabaseHostname=localhost

Guard database that stores keys for guest users. May be the same as above. New guest shards will be created on this database as needed. If not supplied, will use the oxguardDatabaseHostname:

com.openexchange.guard.oxguardShardDatabase=localhost

Username and Password for the databases above:

com.openexchange.guard.databaseUsername=openexchange
com.openexchange.guard.databasePassword=db_password

Open-Xchange REST API host:

com.openexchange.guard.restApiHostname=localhost

Open-Xchange REST API username and password (need to be defined in the OX backend in the "Configure services" below):

com.openexchange.guard.restApiUsername=apiusername
com.openexchange.guard.restApiPassword=apipassword

External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients:

com.openexchange.guard.externalEmailURL=URL_TO_OX

Middleware Configuration on OX Guard node

If you are installing OX Guard on a node that until yet did not host an Open-Xchange middleware you have to additionally configure some parts of the following properties files:

  • configdb.properties: information about the existing configuration database.
  • server.properties: information about the connections have to be set.
  • system.properties: at least SERVER_NAME should be set.

Sevices Configuration

Apache

Configure the mod_proxy_http module by adding the Guard API.

Redhat Enterprise Linux 6 or CentOS 6
$ vim /etc/httpd/conf.d/proxy_http.conf
Debian GNU/Linux 7.0 and SUSE Linux Enterprise Server 11
$ vim /etc/apache2/conf.d/proxy_http.conf
<Proxy balancer://oxguard>
       Order deny,allow
       Allow from all

       BalancerMember http://localhost:8009/ timeout=1800 smax=0 ttl=60 retry=60 loadfactor=100 route=OX1
       ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=ON
       SetEnv proxy-initial-not-pooled
       SetEnv proxy-sendchunked
</Proxy>

ProxyPass /appsuite/api/oxguard balancer://oxguard/oxguard
ProxyPass /pks balancer://oxguard/pgp

Please Note: The Guard API settings must be inserted before the existing <Proxy /appsuite/api> parameter.

Also Note: If you already have a Proxy balancer for the OX backend with the same URL (say http://localhost:8080) then you don't need the second BalacnerMember entry, and you can just have the ProxyPass address that balancer instead.

After the configuration is done, restart the Apache webserver

$ apachectl restart

Open-Xchange

Edit the guard-api.properties configuration file for the OX backend which contain some general Guard settings. Please remove comments in front of the following settings to the configuration file guard-api.properties on the Open-Xchange backend servers:

$ vim /opt/open-xchange/etc/guard-api.properties
# OX GUard general permission, required to activate Guard in the AppSuite UI.
com.openexchange.capability.guard=true

# Default theme template id for all users that have no custom template id configured.
com.openexchange.guard.templateID=0

Configure the API username and password that you assigned to Guard in the server.properties file:

$ vim /opt/open-xchange/etc/server.properties
# Specify the user name used for HTTP basic auth by internal REST servlet
com.openexchange.rest.services.basic-auth.login=apiusername

# Specify the password used for HTTP basic auth by internal REST servlet
com.openexchange.rest.services.basic-auth.password=apipassword

Finally, the OX backend needs to know where the Guard server is located. This is used to notify the Guard server of changes in users, and to send emails marked for signature. The URL for the Guard server should include the URL suffix /guardadmin. In the event of a cluster setup, any Guard server can be referenced here, as it is not session specific, though ideally would have a HTTP load balancer/failover URL:

$ vim /opt/open-xchange/etc/guard-api.properties
# Specifies the URI to the OX Guard end-point; e.g. http://guard.host.invalid:8081/guardadmin
# Default is empty
com.openexchange.guard.endpoint=http://guardserver:8009/guardadmin

Restart the OX backend

$ /etc/init.d/open-xchange restart

SELinux

Running SELinux prohibits your local Open-Xchange backend service to connect to localhost:8009, which is where the Guard backend service listens to. In order to allow localhost connections to 8009 execute the following:

$ setsebool -P httpd_can_network_connect 1

Generating the oxguardpass

Once the Guard configuration (database and backend configuration) and the service configuration has been applied, the Guard administration script needs to be executed in order to create the master password file in /opt/open-xchange/etc/oxguardpass. The initiation only needs to be done once for a multi server setup, for details please see the sections Optional and/or Clustering.

Please Note: If you run a cluster of OX / Guard nodes, only execute this command on ONE node. Not on all nodes! See OX Guard Clustering for details.

$ /opt/open-xchange/sbin/guard --init

Please Note: It is important to understand that the master password file located at /opt/open-xchange/etc/oxguardpass is required to reset user passwords; without them the administrator will not be able to reset user passwords anymore in the future. The file contains the passwords used to encrypt the master database key, as well as passwords used to encrypt protected data in the users table. It must be the same on all Guard servers.

Test Setup

Not required, but it is a good idea to test the Guard setup before starting the initialization. The test function will verify that Guard has a good connection to the OX backend, and that it can resolve email addresses to users.

To test, use an email address that exists on the OX backend (john@example.com for this example)

/opt/open-xchange/sbin/guard --test john@example.com

Guard should return information from the OX backend regarding the user associated with "john@example.com". Problems resolving information for the user should be resolved before using Guard. Check Rest API passwords and settings if errors returned.

Enabling Guard for Users

Guard provides two capabilities for users in the environment as well as a basic "core" level:

  • Guard: com.openexchange.capability.guard
  • Guard Mail: com.openexchange.capability.guard-mail
  • Guard Drive: com.openexchange.capability.guard-drive
  • Guard Documents: com.openexchange.capability.guard-docs

The "core" Guard enabled a basic read functionality for Guard encrypted emails. We recommend enabling this for all users, as this allows all recipients to read Guard emails sent to them. Great opportunity for upsell. Recipients with only Guard enabled can then do a secure reply to the sender, but they can't start a new email or add recipients.

Guard Mail, Guard Drive, and Guard Documents are additional options for users. "Guard Mail" allows users the full functionality of Guard emails. "Guard Drive" allows for encryption and decryption of drive files. "Guard Documents" enable encryption capabilitiy to office documents.

Each of the Guard components is enabled for all users that have the according capability configured. Please note that users need to have the Drive permission set to use Guard Drive. So the users that have Guard Drive enabled must be a subset of those users with OX Drive permission. Since v7.6.0 we enforce this via the default configuration. Those capabilities can be activated for specific user by using the Open-Xchange provisioning scripts:

Guard Mail:

$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-mail=true

Guard Drive:

$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-drive=true

Guard Documents:

$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-docs=true

Please Note: Guard Drive requires Guard Mail to be configured for the user as well. In addition, these capabilities may be configured globally by editing the guard-api.properties file on the OX bakend.

Recipient key detection

Local

Guard needs to determine if an email recipients email address is an internal or external (non-ox) user.

To detect if the recipient is an account on the same OX Guard system there is a mechanism needed to map a recipient mail address to the correct local OX context. The default implementation delivered in the product achieves that by looking up the mail domain (@example.com) within the list of context mappings. That is at least not possible in case of ISPs where different users/contexts use the same mail domain. In case your OX system does not use mail domains in context mappings it is required to deploy an OX OSGi bundle implementing the com.openexchange.mailmapping.MailResolver class or by interfacing Guard with your mail resolver system. Please see OX Guard Mail Resolver for details.

External

Starting with Guard 2.0, Guard will use public PGP Key servers if configured to find PGP Public keys. In addition, Guard will also look up SRV records for PGP Key servers for a recipients domain. This follows the standards OpenPGP Draft.

External PGP servers to use can be configured in the guard.properties file on the Guard servers.

com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371

If you would like this Guard installation discoverable by other Guard servers, then create an SRV record for each domain ("example.com" in this illustration):

_hkp._tcp.open-xchange.com. 28800 IN    SRV     10 1 80 appsuite.example.com.

Please Note PGP Public key servers by default append use the URL server/pks when the record is obtained from an SRV record. The proxy above routes anything with the Apache domain/pks to the OX Guard PGP server.

Clustering

You can run multiple OX Guard servers in your environment to ensure high availability or enhance scalability. OX Guard integrates seamlessly into the existing Open-Xchange infrastructure by using the existing interface standards and is therefor transparent to the environment. A couple of things have to be prepared in order to loosely couple OX Guard servers with Open-Xchange servers in a cluster.

MySQL

The MySQL servers need to be configured in order to allow access to the configdb of Open-Xchange. To do so you need to set the following configuration in the MySQL my.cnf:

bind = 0.0.0.0

This allows the Guard backend to bind to the MySQL host which is configured in the guard-core.properties file with com.openexchange.guard.configdbHostname. After the bind for the MySQL instance is configured and the OX Guard backend would be able to connect to the configured host, you have to grant access for the OX Guard service on the MySQL instance to manage the databases. Do so by connecting to the MySQL server via the MySQL client. Authenticate if necessary and execute the following, please note that you have to modify the hostname / IP address of the client who should be able to connect to this database, it should include all possible OX Guard servers:

GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY secret;

Apache

OX Guard uses the Open-Xchange REST API to store and fetch data from the Open-Xchange databases. The REST API is a servlet running in the Grizzly container. By default it is not exposed as a servlet through Apache and is only accessibly via port 8009. In order to use Apache's load balancing via mod_proxy we need to add a servlet called "preliminary" to proxy_http.conf, example based on a clustered mod_proxyconfiguration:

<Location /preliminary>
     Order Deny,Allow
     Deny from all
     # Only allow access from Guard servers within the network. Do not expose this
     # location outside of your network. In case you use a load balancing service in front
     # of your Apache infrastructure you should make sure that access to /preliminary will
     # be blocked from the Internet / outside clients. Examples:
     # Allow from 192.168.0.1
     # Allow from 192.168.1.1 192.168.1.2
     # Allow from 192.168.0.
</Location>

ProxyPass /preliminary balancer://oxcluster/preliminary

Make sure that the balancer is properly configured in the mod_proxy configuration. Examples on how to do so can be found in our clustering configuration for Open-Xchange AppSuite. Like explained in the example above, please make sure that this location is only available in your internal network, there is no need to expose /preliminary to the public, it is only used by Guard servers to connect to the OX backend. If you have a load balancer in front of the Apache cluster you should consider blocking access to /preliminary from WAN to restrict access to the servlet to internal network services only.

Now add the OX Guard BalancerMembers to the oxguard balancer configuration (also in proxy_http.conf) to address all your OX Guard nodes in the cluster in this balancer configuration. The configuration has to be applied to all Apache nodes within the cluster.

If the Apache server is a dedicated server / instance you also have to install the OX Guard UI-Static package on all Apache nodes in the cluster in order to provide static files like images or CSS to the OX Guard client. Example for Debian (the OX Guard repository has to be configured in the package management prior):

$ apt-get install open-xchange-guard-ui-static

Open-Xchange

Disable the Open-Xchange IPCheck for session verification. This is required because OX Guard will use the users session cookie to connect to the Open-Xchange REST API, but as a different IP address than the OX Guard server has been used during authentication the request would fail if you don't disable the IPCheck:

$ vim /opt/open-xchange/etc/server.properties

and set:

com.openexchange.IPCheck=false

The OX Guard UI package has to be installed on all Open-Xchange backend nodes as well, example for Debian (the OX Guard repository has to be configured in the package management prior):

$ apt-get install open-xchange-guard-ui

Restart the Open-Xchange service afterwards.

OX Guard

For details in clustering Guard servers, please see OX Guard Clustering. It is critical that all Guard servers have the same oxguardpass file. Please see the clustering link for details. Do not run /opt/open-xchange/sbin/guard --init on more than one server.

After all the services like MySQL, Apache and Open-Xchange have been configured you need to update the OX Guard backend configuration to point to the correct API endpoints. Set the REST API endpoint to an Apache server by setting the following value in /opt/open-xchange/etc/guard-core.properties:

com.openexchange.guard.restApiHostname=apache.example.com

Per default Guard will try to connect to port 8009 to this host, but as we configured the REST API to be proxies thorugh the servlet /preliminary on every Apache we now also need to change the target port for the REST API. You can do so by adding the following line into /opt/open-xchange/etc/guard-core.properties:

com.openexchange.guard.oxBackendPort=80

Please also change all settings in regards to MySQL like com.openexchange.guard.configdbHostname, com.openexchange.guard.oxguardDatabaseHostname, com.openexchange.guard.databaseUsername or om.openexchange.guard.databasePassword.

Afterwards restart the OX Guard service and check the log file if the OX Guard backend is able to connect to the configured REST API.

Multi Node

If you have multiple OX and Guard installations, please see the following documentation OX Guard Modular Setup.

Support API

The OX Guard Support API enables administrative access to various functions for maintaining OX Guard from a client in a role as a support employee. A client has to do a BASIC AUTH authentication in order to access the API. Username and password can be configured in the guard-core.properties file using the following settings:

# Specify the username and password for accessing the Support API of Guard
com.openexchange.guard.supportApiUsername=
com.openexchange.guard.supportApiPassword=

In contrast to the rest of the OX Guard requests, the OX Guard support API requests are accessible using: /guardsupport. This distinction allows more flexible configuration since the support API should not always be accessible from everywhere.

Warning: Exposing the support API to the internet could be huge security risk. Only add to Apache if you know what you are doing.


Reset password

POST /guardsupport/?action=reset_password

Performs a password reset and sends a new random generated password to a specified email address by the user or a default address if the user did not specify an email address. (Since Guard 2.0)

Parameters:

  • email – The email address of the user to reset the password for
  • default (optional) – The email address to send the new password to, if the user did not specify a secondary email address

Response: PRIMARY if the reset was sent to the primary email address. SECONDARY if the reset email was sent to the secondary email address that the user specified

Expose key

POST /guardsupport/?action=expose_key

Marks a deleted user key temporary as “exposed” and creates a unique URL for downloading the exposed key. Automatic resetting of exposed keys to "not exposed" is scheduled once a day and resets all exposed keys which have been exposed before X hours, where X can be configured using com.openexchange.guard.exposedKeyDurationInHours in the guard.properties files. (Since Guard 2.0)

Parameters:

  • email – The email address of the user to expose the deleted keys for
  • cid – The context id

Response: A URL pointing to the downloadable exposed keys.

Delete user

POST /guardsupport/?action=delete_user

Deletes all keys related to a certain user. The keys are backed up and can be exposed using the “expose_key” call. (Since Guard 2.0)

Parameters:

  • user_id – The user's id
  • cid - The context id

Upgrade User (Release 2.10 and later)

POST /guardsupport/?action=upgrade_guest

Upgrades a Guest account. This action copies all of the keys from the Guest account to a full OX account, assuming that user has Guard capabilities.

Parameters:

  • email - The email address of the Guest user
  • user_id – The user's new id
  • cid - The user's new context id

Customisation

Guard's templates are customisable at the user and context level. Please see Customisation for details.

Entropy

Guard requires entropy (randomness) to generate the private/public keys that are used. Depending on the server and it's environment, this may become a problem. Please see Entropy for a possible solution.