Close menu

Customisations

Customisations

Some Carbonio customizations are included in this section. The installation instructions for the Carbonio Docs Custom Fonts have been relocated to the Carbonio User Guides area.

NGINX Schemas

An administrator could want to modify NGINX for a number of reasons, such as providing a unique header for internal audit. The NGINX configuration file will be rewritten after upgrades, thus editing it is not an option. The most practical choice is to utilise a template provided by NGINX. The rest of this section will provide some functioning NGINX information that is important to customizations before demonstrating the process.\

NGINX creates its initial configuration from files in two directories: /opt/zextras/conf/nginx/templates  which are then processed and saved in /opt/zextras/conf/nginx/includes, which are then read and utilised during regular operations. A separate directory called  /opt/zextras/conf/nginx/template_custom,  includes files that override settings in the equivalent files in the templates directory, allowing for customised adjustments.

In other words, whenever the configuration is read, if a file with the same name exists in the  templates  and templates_custom folders, the one in the templates_custom  directory is utilised.

This implies that a user must alter the built-in nginx.conf.web.http.default.template  template instead of storing preferences in a file with a specific filename.

Custom Configuration

Now, to implement the configuration mentioned at the beginning of this section, the procedure is the following.

  1. Copy file over to the custom directory.

    # cp /opt/zextras/conf/nginx/templates/nginx.conf.web.http.default.template \
  /opt/zextras/conf/nginx/template_custom/nginx.conf.web.http.default.template

  2. Edit file /opt/zextras/conf/nginx/template_custom/nginx.conf.web.http.default.template to add the custom header. Search for the location directive to which you want to add the custom header and add the following line:

    proxy_set_header X-CUSTOM-Forwarded-For "audit@example.com";

    The resulting configuration would look similar to the following

    location = /
{
  if ($http_cookie !~ "ZM_AUTH_TOKEN=") {
      return 307 "/static/login/";
  }

proxy_set_header X-CUSTOM-Forwarded-For "audit@example.com";
}

  3. Restart the proxy system as the zextras user.

    zextras$ zmproxyctl restart

    NGINX will generate the configuration from the template files, then start.

Update of Customisations

When a customisation is operational, the template does usually not need any modification until the next update of NGINX. When updated NGINX packages are available, it is suggested to check for any changes in the default configuration, to find if any incompatible values has been introduced or if some directive has been removed, modified, or added. In case in the new packages the default template has changed, the differences must be reflected in the customised template, because otherwise the NGINX service may not start properly.

Remove the Customisations

To remove the customisation, simply remove the customised template and restart the proxy.

A few things are worth mentioning:

  • Every time a customised template is used, the processed file (the one located in the includes directory) will add a header indicating that the configuration was created using a customised template and providing instructions on how to return to the default.
  • Which template is selected and to which file it is saved will be recorded in the log file.