Caution: This documentation is for eZ Publish legacy, from version 3.x to 5.x.
For 5.x documentation covering Platform see eZ Documentation Center, for difference between legacy and Platform see 5.x Architecture overview.

Site management

This part of the 4.x documentation is for eZ Publish 4.0, only reference section is common for all eZ Publish 4.x versions as well as eZ Publish 5.x "LegacyStack", please select the version you are using for the most up to date documentation!

A single eZ Publish installation is capable of hosting multiple sites by making use of something called the siteaccess system. This system makes it possible to use different configuration settings based on a set of rules. The rules control which group of settings that should be used in a particular case. The siteaccess rules must be specified in the global override for the site.ini configuration file ("/settings/override/site.ini.append.php").

Siteaccess

A collection of configuration settings is called a siteaccess. When a siteaccess is in use, the default configuration settings will be overridden by the settings that are defined for the siteaccess. Among other things, a siteaccess dictates which database, design and var directory that should be used (these are sometime referred to as "resources"). By making use of different siteaccesses, it is possible to combine different content and designs. A typical eZ Publish site consists of two siteaccesses: a public interface for visitors and a restricted interface for administrators. Both siteaccesses use the same content (same database and same var directory) but they use different designs. While the administration siteaccess would most likely use the built in administration design, the public siteaccess would use a custom design. The following illustration shows this scenario.

Example of a setup with two siteaccesses.

Example of a setup with two siteaccesses.

A siteaccess is nothing more than a set of configuration files that override the default settings when the siteaccess is used. A single eZ Publish installation can virtually host an unlimited number of sites by the way of siteaccesses. The configuration settings for a siteaccess are located inside a dedicated subdirectory within the "/settings/siteaccess" directory. The name of the subdirectory is the actual name of the siteaccess.

Rules for siteaccess names

eZ Publish has a set of characters that are allowed for a siteaccess name. They are the alphanumerical characters (the [a-z], [A-Z] and [0-9] ranges), and the "_" (underscore).

These are the simple rules for characters converting:

  • Characters not in the previous list (alphanumerical and underscore) are replaced by an "_" (underscore);
  • Multiple consecutive "_" (underscores) are replaced by a single underscore;
  • Leading and trailing "_" are removed.

Examples: You can have an http://example.org/ and an http://admin.example.org/sites, where the hostname is used for matching the SA. In this case, example.org will be changed to example_org and admin.example.org to admin_example_org. Another example is an URL with a space: http://example.com/main area/ which would lead to SA "main_area".

The rules above are only valid for the element URIMatchType option.
Note: If you don't want the transformation to be done, you can use URIMatchType=map instead.

The following illustration shows a setup with two siteaccesses: admin and public.

Siteaccess directory example.

Siteaccess directory example.

When a siteaccess is in use, eZ Publish reads the configuration files using the following sequence:

0 - Default configuration settings - /settings/*.ini?
1 - Active extension siteaccesses - /extension/my_extension/settings/siteaccess/my_site/*.ini.append.php
2 - Siteaccesses - /settings/siteaccess/my_site/*.ini.append.php?
3 - Active extensions - /extension/my_extension/settings/*.ini[.append.php]?
4 - Global overrides - /settings/override/*.ini.append.php

In other words, eZ Publish will first read the default configuration settings. Secondly it will read my_site/*.ini.append.php to find the siteaccesses for the active extensions for the installation. Then it will determine which siteaccess to use based on the rules that are defined in the global override for "site.ini" ("/settings/override/site.ini.append.php"). When it knows which siteaccess to use, it will go into the directory of that siteaccess and read the configuration files that belong to that siteaccess. Next it will go into the configuration file for the active extensions and read the configuration files for the active extensions. The settings of the siteaccess will override the default configuration settings.

For example, if the siteaccess uses a database called "Amiga", the system will see this and automatically use the specified database when an incoming request is processed. Finally, eZ Publish reads the configuration files in the global override directory. The settings in the global override directory will override all other settings. In other words, if a database called "CD32" is specified in the global override for "site.ini" then eZ Publish will attempt to use that database regardless of what is specified in the siteaccess settings. If a setting is not overridden by either the siteaccess or from within a global override then the default setting will be used. The default settings are set by the ini files located in the "/settings" directory.

The following figure illustrates how the system reads the configuration files using the "site.ini" file as an example. As already mentioned, settings placed in the override files will be used instead of the default ones.

Configuration override example.

Configuration override example.

Rules for Online Editor and extensions

This applies for Online Editor and other extensions:
 if a configuration array is initialized in "extension/<extension_name>/settings/<ini_file>" and you want to insert a new value into this array:
 1. Do not edit "extension/<extension_name>/settings/<ini_file>", because it will be overwritten next time when you upgrade the extension.
 2. Do not create "extension/<extension_name>/settings/siteaccess/<siteaccess_name>/<ini_file>", because it will be overridden by "extension/<extension_name>/settings/<ini_file>".
 3. Do not create or edit "settings/siteaccess/<siteaccess_name>/<ini_file>", because it will be overriden by "extension/<extension_name>/settings/<ini_file>".
 4. To affect all siteaccesses where <extension_name> is used, specify new value in "settings/override/<ini_file>".
 5. To only affect a certain siteaccess, you need to use the following workaround:
 - create a new custom extension specially for these settings: "extension/<custom_extension>/"
 - specify new value in "extension/<custom_extension>/settings/<ini_file>"
 - enable the custom extension for the target siteaccess by adding

ActiveAccessExtensions[]=<custom_extension>

 to "settings/siteaccess/<siteaccess_name>/site.ini.append.php"
 - make sure the configuration array is not re-initialized in "settings/override/<ini_file>" (if exists).

Note: The name of <ini_file> here should always contain either ".append" or ".append.php" in the end. The only exception are default configuration files (for example "settings/design.ini" or "extension/ezoe/settings/ezoe.ini").

Executable packages warning

This issue affects installations using eZ Publish Legacy, either stand-alone, or as part of eZ Platform 5.x, or in eZ Platform 1.11 and newer using LegacyBridge. If you are not using Legacy in any way, you are not affected.

The package system, by design, allows you to package an extension into a file, and export/import such packages. Extensions can of course contain PHP scripts, and they usually do. Such scripts can be used in an attack on the server. This problem is fundamental and cannot be fixed by any other means than by removing the feature.

By default, only the Administrator has the permissions to use the package system. It follows that the Administrator role, and any others granted packaging permissions, can only be held by users who already have access to the server, and/or can be trusted not to exploit this access.

As a consequence eZ Publish legacy should not be used in the type of shared hosting installation where Administrators are not supposed to have access to the underlying operating system, or to other eZ Publish installations on the same server. The package system is an old part of eZ Publish legacy, and it was not designed for that kind of installation. Currently this is not considered best practice anyway - setups using e.g. Docker and Platform.sh allow you to completely separate installations from each other. This is a better way to keep things secure than relying on PHP scripts being read-only even for administrators. (The package system does not exist in eZ Platform and will not be added there, since extensions are not used there.)

In summary:

If you are responsible for legacy installations where administrators cannot be fully trusted not to exploit their privileges, make sure to properly lock down the package system and/or fully separate web sites from each other.
 Make sure that the administrator password(s) are secure, and not using the default administrator password.

Proposed quick solution for those affected:

If you are administrating a shared hosting solution of this kind, it may take a while to change the setup. Meanwhile, one quick way to lock down the package system is to use rewrite rules to block all access to package URLs. Apache example:

RewriteRule ^/package/.* - [R=403,L]

or with URL-based SiteAccess:

RewriteRule ^/my_site_access/package/.* - [R=403,L]

or supporting both cases, and multiple SiteAccesses:

RewriteRule ^(/my_site_access|/my_site_access_admin)?/package/.* - [R=403,L]

This can be placed before other rules.

To be absolutely certain you can also (or instead of this) delete the /kernel/package directory in the eZ Publish web root. Please note that this will break the legacy installation wizard, since it relies on the package system to install the demo design.

Once the situation is resolved these measures should be reversed, to bring back the package features. You may want to do a review of whether the issue may have been exploited on your server(s).

Balazs Halasy (01/02/2005 2:27 pm)

Dominika Kurek (27/02/2018 7:54 am)

Geir Arne Waaler, Andrea Melo, Ricardo Correia, Dominika Kurek


Comments

  • Sequence of the override files

    When a siteaccess is in use, it seems more LOGIC for eZ publish to read the configuration files using the following sequence:

    1. Default configuration settings (/settings/*.ini)
    2. Global overrides (/settings/override/*.ini.append.php)
    3. Siteaccess settings (/settings/siteaccess/[name_of_siteaccess]/*.ini.append.php)

    I think, for example, that the database settings in the global override directory SHOULD be overrided by the database settings in the siteaccess. Otherwise if we have several databases for multisites, the different databases settings in the different siteaccess are overrided by the same database sittings in the global overrides, some sites would't work.

    • Re: Sequence of the override files

      "I think, for example, that the database settings in the global override directory SHOULD be overrided by the database settings in the siteaccess. Otherwise if we have several databases for multisites, the different databases settings in the different siteaccess are overrided by the same database sittings in the global overrides, some sites would't work."

      In that case, you should not use the global override to set the database settings. You would have to set the database settings in every site's siteaccess file.
      • Re: Re: Sequence of the override files

        Supposing multisites include many sites with the same database, for instance, 10 sites. I can set the database db in the global overrides only one time. Some day I want to site1 with a separate database db1. How can I do?

        According to your sequence to read the configuration files:
        1. Default configuration settings (/settings/*.ini)
        2. Siteaccess settings (/settings/siteaccess/[name_of_siteaccess]/*.ini.append.php)
        3. Global overrides (/settings/override/*.ini.append.php)

        I have to:
        --- set the db1 in this siteaccess setting file for site1;
        --- delete the db settings in the global override file, or db1 will be overrided by db settings;
        --- set the same db one by one in other siteaccess setting files, 9 files for this example.

        But according to the following sequence to read the configuration files:
        1. Default configuration settings (/settings/*.ini)
        2. Global overrides (/settings/override/*.ini.append.php)
        3. Siteaccess settings (/settings/siteaccess/[name_of_siteaccess]/*.ini.append.php)

        I only need set the db1 in this siteaccess setting file for site1, that's all.

        I needn't delete the db settings in the global override file, because the db will be overrite by db1. Also I don't worry about other sites. Do nothing for other 9 sites.

        Think about other setting parameters, there is the same situation. That's why I think the latter seems more LOGIC.
        • Re: Re: Re: Sequence of the override files

          I'm sorry but I'm not agree with you, because as kyle says, you can solve your problem by deleting database settings in the global override and managing this settings per site access.

          On the other side I have exactly the opposite need, and you couldn't find a solution if global settings are overrided by siteaccess settings :

          I need to allow my siteaccess owners to modify their templates and settings (including site.ini) but I don't want they use another database, and I don't want they know my database password. They must use the same database for all siteaccesses.
          It's just a different LOGIC ! ;-)



  • You may add more info about extension

    You can place a lot of common settings in a common extension:
    Smart example (for sites with only different lang):

    $ cat settings/siteaccess/en/site.ini.append.php; echo
    <?php /* #?ini charset="iso-8859-15"?

    [ExtensionSettings]
    ActiveAccessExtensions[]=in_common
    ActiveAccessExtensions[]=in_lang_en

    */ ?>

    $diff -Naur extension/in_lang_en/settings/site.ini.append.php extension/in_lang_de/settings/
    --- extension/in_ber_lang_en/settings/site.ini.append.php 2005-09-30 15:32:34.000000000 +0200
    +++ extension/in_ber_lang_de/settings/site.ini.append.php 2005-09-30 15:33:13.000000000 +0200
    @@ -1,16 +1,16 @@
    <?php /* #?ini charset="iso-8859-15"?

    [SiteSettings]
    -SiteName=[en]
    +SiteName=[de]
    -SiteURL=http://www.example.it/en
    +SiteURL=http://www.example.it/de

    [RegionalSettings]
    -Locale=eng-US
    -ContentObjectLocale=eng-US
    +Locale=ger-DE
    +ContentObjectLocale=ger-DE
    TextTranslation=enabled

    [ContentSettings]
  • Extensions

    Here the information about extensions are missing. This is the correct order when using settings in extensions:

    1. Default configuration settings (/settings/*.ini)
    2. Siteaccess settings (/settings/siteaccess/[name_of_siteaccess]/*.ini.append.php)
    4. Ative Extensions (/extension/*/settings/*.ini.append.php)
    3. Global overrides (/settings/override/*.ini.append.php)
  • Extensions update

    This is the order, including extension site accesses:

    1. Default configuration settings (/settings/*.ini)
    2. Active extension siteaccesses (/extension/*/settings/siteaccess/[name_of_siteaccess]/*.ini.append.php)
    3. Siteaccesses (/settings/siteaccess/[name_of_siteaccess]/*.ini.append.php)
    4. Active extensions (/extension/*/settings/*.ini.append.php)
    5. Global overrides (/settings/override/*.ini.append.php)
    • Re: Extensions update

      Agree, added an issue http://issues.ez.no/12939 for this, it's on our todo list.
  • Question about the loading sequence

    If i set the HostMatchItems or AvailableSiteAccessList in globle override, and the globle override is loaded after the siteaccess.
    How can EZ know which siteaccess should be loaded?