aggregator2: update the documentation to reflect the latest changes and features.

modules/aggregator2/docs/aggregator2.txt

 aggregator2 Module
 ==================
 
-This is an experimental module for aggregating metadata.
-It is designed to preserve most of the common metadata items, and also attempt to preserve unknown elements.
+This is a module for metadata aggregation. It is designed to preserve most of the common metadata items, and it also
+attempts to preserve unknown elements. Metadata sources are parsed and rebuilt, so small differences between the
+original sources and the metadata generated may occur. More specifically:
 
-*Note*: This aggregator only works on XML metadata, and does its work independently of the of other parts of simpleSAMLphp, such as the `metarefresh` module.
+* Signatures will be removed from every signed metadata source.
+* All sources will be wrapped up in an `EntitiesDescriptor` element.
+
+*Note*: This aggregator works only with XML metadata, and does its work independently of other parts of SimpleSAMLphp,
+such as the `metarefresh` module.
 
 
 Configuration
@@ -13,11 +18,10 @@ Configuration
 This module is configured through the `config/module_aggregator2.php` configuration file.
 An example file is available in `modules/aggregator2/config-templates/`:
 
-    cd /var/simplesaml
     cp modules/aggregator2/config-templates/module_aggregator2.php config/
 
 The configuration file contains one or more aggregators in the configuration array.
-The index in the configuration array gives the identifier of the aggregator.
+The index for each item in the configuration array gives the identifier of the aggregator.
 
 
 ### Aggregator entry configuration
@@ -25,52 +29,87 @@ The index in the configuration array gives the identifier of the aggregator.
 The aggregator can be configured with the following options:
 
 `sources`
-:   Array which describes which metadata we should download.
+:   Array which describes a source from which we should download metadata.
 
 `cron.tag`
-:   Can be used to periodically run an update.
-    Only useful when you have enabled caching of metadata.
+:   Can be used to run periodical updates. It will only be useful when you have metadata caching enabled.
 
 `cache.directory`
-:   A path to a directory where the aggregator will cache downloaded and generated metadata.
-    This directory must be writeable by the webserver.
+:   The path to a directory where the aggregator will cache downloaded and generated metadata.
+    This directory must be writable by the web server.
 
 `cache.generated`
-:   The number of seconds generated metadata should be cached.
-    If this option is unset, the generated metadata will not be cached.
+:   The number of seconds the generated metadata will be cached for.
+
+:    *Note*: generated metadata will not be cached if this option is unset.
 
 `valid.length`
-:   The number of seconds the generated metadata should be valid.
-    This is used to set the validUntil attribute on the generated metadata.
-    The default is one week.
+:   The number of seconds the generated metadata should be valid for.
+    This is used to set the `validUntil` attribute on the generated metadata.
+    Defaults to one week..
 
-:   *Note*: The `cache.generated` option must be smaller than this option, otherwise you will end up returning outdated metadata.
+:   *Note*: The value of the `cache.generated` option must be smaller than the value here, otherwise you would end up
+    returning outdated metadata.
 
 `ssl.cafile`
-:   This option enables validation of the server certificate when fetching metadata over https.
-    It must be set to a path to a PEM-file which contains one or more valid CA certificates.
-    The path can be absolute, or it can be relative to the `cert`-directory.
+:   This option enables validation of the server certificate when fetching metadata over HTTPS. It must be a path
+    pointing to a PEM file which contains one or more valid CA certificates. The path can be either absolute or
+    relative to the `cert` directory.
 
 :   *Note*: This option can be overridden for each metadata source.
 
 `sign.privatekey`
-:   The private key that should be used to sign the metadata, in PEM format.
-    The path to the private key can be absolute, or it can be relative to the `cert`-directory. Skip this option or
-    set it to NULL if you don't want to sign the generated metadata.
+:   The private key that should be used to sign the resulting metadata, in PEM format. The path to the private key can
+    be either absolute or relative to the `cert` directory. Skip this option or set it to `NULL` if you don't want to
+    sign the generated metadata.
 
 `sign.privatekey_pass`
-:   The password for the private key.
-    If this option is unset, the private key is assumed to be unencrypted.
+:   The password used to encrypt the private key. If this option is unset, the private key is assumed to be unencrypted.
 
 `sign.certificate`
-:   The certificate which contains the public key corresponding to the private key, in PEM format.
-    This certificate is included in the generated metadata.
-    The path to the certificate can be absolute, or it can be relative to the `cert`-directory.
+:   The certificate that contains the public key corresponding to the private key, in PEM format. The path to the
+    certificate can be either absolute or relative to the `cert` directory.
+
+:   *Note*: This certificate will be included in the generated metadata.
 
 `RegistrationInfo`
-:   Allows to specify information about the registrar of this metadata. Please refer to the
+:   Allows to specify information about the registrar of the generated metadata. Please refer to the
     [MDRPI extension](./simplesamlphp-metadata-extensions-rpi) document for further information.
 
+`exclude`
+:   Allows to exclude one or more entities from the generated metadata, represented by their entity IDs. Can be either
+    a string with the entity ID of a single entity, or an array of strings with all the entity IDs to exclude from
+    the result.
+
+:   *Note*: this option will not exclude the entities from the cached metadata sources. It will only act as a default
+    configuration for the generation of the metadata aggregate, and therefore can be overridden per request.
+
+`filter`
+:   One or more sets representing the types of entities that should be included in the generated metadata. Filtering
+    will be performed depending on the role of the entity, as well as the protocols it supports. Can be either a string
+    with the set of entities desired, or an array of strings with all the different sets to filter by. The following
+    sets are available:
+
+*   `saml2`
+:   All the entities that support the SAML 2.0 protocol.
+*   `shib13`
+:   All the entities that support the SAML 1.1 protocol.
+*   `saml20-idp`
+:   All the identity providers that support the SAML 2.0 protocol.
+*   `saml20-sp`
+:   All the service providers that support the SAML 2.0 protocol.
+*   `saml20-aa`
+:   All the attribute authorities that support the SAML 2.0 protocol.
+*   `shib13-idp`
+:   All the identity providers that support the SAML 1.1 protocol.
+*   `shib13-sp`
+:   All the service providers that support the SAML 1.1 protocol.
+*   `shib13-aa`
+:   All the attribute authorities that support the SAML 1.1 protocol.
+
+:   *Note*: this option will not filter the entities in the cached metadata sources. It will only act as a default
+    configuration for the generation of the metadata aggregate, and therefore can be overriden per request.
+
 
 ### Aggregator source configuration
 
@@ -78,41 +117,55 @@ The aggregator can be configured with the following options:
 :   The URL the metadata should be fetched from.
 
 `ssl.cafile`
-:   This option enables validation of the server certificate when fetching metadata over https.
-    It must be the path to a PEM-file which contains one or more valid CA certificates.
-    The path can be absolute, or it can be relative to the `cert`-directory.
+:   This option enables validation of the server certificate when fetching metadata over HTTPS. It must be a path
+    pointing to a PEM file which contains one or more valid CA certificates. The path can be either absolute or
+    relative to the `cert` directory.
 
-:   *Note*: This option overrides the aggregator option.
+:   *Note*: This option overrides the option with the same name in the root configuration for the an aggregator.
 
 `cert`
-:   Check the signature on the metadata against the specified certificate.
-    The path to the certificate can be absolute, or it can be relative to the `cert`-directory.
+:   The certificate that should be used to check the signature of this metadata document, in PEM format. The path to
+    the certificate can be either absolute or relative to the `cert` directory.
 
-:   *Note*: This can not be a CA certificate.
-    Validation against a CA certificate is not supported.
+:   *Note*: This cannot be a CA certificate. Validation against CA certificates (PKI) is not supported.
 
 
 Retrieving aggregated metadata
 ------------------------------
 
-The metadata can be downloaded from the following location:
+You will find a link to the aggregator2 module in the *Federation* tab of SimpleSAMLphp's web interface. There you will
+be able to see a list of all the metadata aggregates you have configured, and see or download them in different
+formats.
+
+In general, metadata aggregates can be downloaded from the following location:
+
+    http://<YOUR HOST>/simplesaml/modules.php/aggregator2/get.php?id=<aggregator id>
+
+where the *aggregator id* is the identifier you used as an index for the aggregator configuration array. Additionally,
+you can use the following parameters to customize the resulting metadata aggregate:
+
+`exclude`
+:   Allows to exclude one or more entities from the generated metadata, represented by their entity IDs. If you need to
+    specify more than one entity, use a comma-separated list of entity IDs.
 
-    http://<server>/simplesaml/modules.php/aggregator2/get.php?id=<aggregator id>
+`filter`
+:   Allows to filter by sets specifying the type of entities or the protocols they support. If you need to specify more
+    than one set, use a comma-separated list. See the configuration option with the same name to get a list of all
+    the sets supported.
 
 
 Asynchronous metadata updates
 -----------------------------
 
-By default, the `aggregator2` module will update the metadata when receiving a request.
-For performance reasons, it is recommended to run the updates asynchronously.
-By doing this, the aggregated metadata will be generated in the background.
+By default, the `aggregator2` module will update the metadata upon receiving a request. For performance reasons, it is
+recommended to run the updates asynchronously. By doing this, the aggregated metadata will be generated in the
+background.
 
-To enable this, you must configure a cache directory with the `cache.directory` option.
-This directory must be writeable by the web server.
-You can then enable caching of generated metadata by setting the `cache.generated` option to the number of seconds the metadata can be cached.
+To enable this, you must configure a cache directory with the `cache.directory` option. This directory must be writable
+by the web server. You can then enable caching of generated metadata by setting the `cache.generated` option to the
+number of seconds the metadata should be cached.
 
-You will now have a configuration that caches both downloaded and generated metadata.
-It will however still update the metadata when the user accesses the aggregator endpoint
-To update the generated metadata in the background, you must add a `cron.tag` option.
-This option must reference a cron tag entry configured in `module_cron.php`.
-Once this is done, your aggregated metadata will be updated everytime that cron entry is executed.
+You will now have a configuration that caches both downloaded and generated metadata. However, it will still update the
+metadata when the user accesses the aggregator endpoint. To update the generated metadata in the background, you must
+add a `cron.tag` option. This option must reference a cron tag entry configured in `module_cron.php`. Once this is
+done, your aggregated metadata will be updated every time that cron entry is executed.