You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@syncope.apache.org by il...@apache.org on 2016/08/26 16:10:45 UTC
syncope git commit: [SYNCOPE-700] Finalizing reference guide content
Repository: syncope
Updated Branches:
refs/heads/master 98703d1c7 -> 88602c0bb
[SYNCOPE-700] Finalizing reference guide content
Project: http://git-wip-us.apache.org/repos/asf/syncope/repo
Commit: http://git-wip-us.apache.org/repos/asf/syncope/commit/88602c0b
Tree: http://git-wip-us.apache.org/repos/asf/syncope/tree/88602c0b
Diff: http://git-wip-us.apache.org/repos/asf/syncope/diff/88602c0b
Branch: refs/heads/master
Commit: 88602c0bbdd9bc1aea560676225d12ca71c588d0
Parents: 98703d1
Author: Francesco Chicchiricc� <il...@apache.org>
Authored: Fri Aug 26 18:10:15 2016 +0200
Committer: Francesco Chicchiricc� <il...@apache.org>
Committed: Fri Aug 26 18:10:15 2016 +0200
----------------------------------------------------------------------
src/main/asciidoc/getting-started/obtain.adoc | 44 ------
src/main/asciidoc/images/installer-12.png | Bin 375102 -> 72643 bytes
src/main/asciidoc/images/installer-13.png | Bin 72643 -> 39897 bytes
src/main/asciidoc/images/installer-14.png | Bin 39897 -> 0 bytes
.../adminconsole/adminconsole.adoc | 2 +-
.../workingwithapachesyncope/customization.adoc | 29 ++--
.../systemadministration/activitimodeler.adoc | 46 ++++++
.../configurationparameters.adoc | 44 ++++++
.../configureconnidlocations.adoc | 72 +++++++++
.../systemadministration/connectorbundles.adoc | 124 +++++++++++++++
.../systemadministration/dbms.adoc | 152 +++++++++++++++++++
.../systemadministration/domainsmanagement.adoc | 35 +++++
.../emailconfiguration.adoc | 32 ++++
.../systemadministration/highavailability.adoc | 52 +++++++
.../systemadministration/importexport.adoc | 83 ++++++++++
.../systemadministration/javaeecontainer.adoc | 113 ++++++++++++++
.../setadmincredentials.adoc | 49 ++++++
.../systemadministration.adoc | 73 +++++++++
.../workingwithapachesyncope.adoc | 18 +--
19 files changed, 892 insertions(+), 76 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/syncope/blob/88602c0b/src/main/asciidoc/getting-started/obtain.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/getting-started/obtain.adoc b/src/main/asciidoc/getting-started/obtain.adoc
index a1e81a4..2b205cd 100644
--- a/src/main/asciidoc/getting-started/obtain.adoc
+++ b/src/main/asciidoc/getting-started/obtain.adoc
@@ -225,68 +225,24 @@ image::installer-3.png[installer-3]
image::installer-4.png[installer-4]
-Installation path::
-* installation path: is the directory where Syncope overlay will be created
-
image::installer-5.png[installer-5]
-Maven::
-* *Maven home directory:* is the Maven home directory;
-* *Group ID:* something like 'com.mycompany' - maven overlay property;
-* *Artifact ID:* something like 'myproject' - maven overlay property;
-* *Secret Key:* Provide any pseudo-random, 16 character length, string here that will be used in the generated project for AES ciphering;
-* *Anonymous Key:* - Provide any pseudo-random, 16 character length, string here that will be used in the generated project for AES ciphering;
-* *Configuration directory:* where Syncope configuration files are stored;
-* *Log directory:* where Syncope logs are stored;
-* *Bundle directory:* where ConnId bundles are stored;
-* *Syncope version:* the project version that would be to install.
-
image::installer-6.png[installer-6]
-Syncope options::
-* *Swagger:* check if you want to install http://swagger.io[Swagger UI^];
-* *Camel:* check if you want to install http://camel.apache.org[Camel provisioning^];
-* *Activiti workflow modeler:* check if you want to install http://activiti.org[Activiti modeler^] (default is true);
-
image::installer-7.png[installer-7]
-Database::
-* DBMS where Syncope will be installed;
-
image::installer-8.png[installer-8]
-Database settings::
-* Depends on DBMS selected (in the example: PostgreSQL)
-** Database JDBS url;
-** Database user;
-** Database password;
-
image::installer-9.png[installer-9]
-Application server::
-* Container where Syncope will be deployed;
-
image::installer-10.png[installer-10]
-Application server settings::
-* Depends on container selected (in the example: Tomcat)
-
-The next images shows how the installer print some feedback directly on the GUI or reading the log file under the
-configuration directory:
-
-[source]
---
-/var/tmp/syncope_2_0_0/install.log
---
-
image::installer-11.png[installer-11]
image::installer-12.png[installer-12]
image::installer-13.png[installer-13]
-image::installer-14.png[installer-14]
-
[[installer-components]]
==== Components
http://git-wip-us.apache.org/repos/asf/syncope/blob/88602c0b/src/main/asciidoc/images/installer-12.png
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/images/installer-12.png b/src/main/asciidoc/images/installer-12.png
index 692790f..0bc120e 100644
Binary files a/src/main/asciidoc/images/installer-12.png and b/src/main/asciidoc/images/installer-12.png differ
http://git-wip-us.apache.org/repos/asf/syncope/blob/88602c0b/src/main/asciidoc/images/installer-13.png
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/images/installer-13.png b/src/main/asciidoc/images/installer-13.png
index 0bc120e..8fbf70f 100644
Binary files a/src/main/asciidoc/images/installer-13.png and b/src/main/asciidoc/images/installer-13.png differ
http://git-wip-us.apache.org/repos/asf/syncope/blob/88602c0b/src/main/asciidoc/images/installer-14.png
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/images/installer-14.png b/src/main/asciidoc/images/installer-14.png
deleted file mode 100644
index 8fbf70f..0000000
Binary files a/src/main/asciidoc/images/installer-14.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/syncope/blob/88602c0b/src/main/asciidoc/reference-guide/workingwithapachesyncope/adminconsole/adminconsole.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/adminconsole/adminconsole.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/adminconsole/adminconsole.adoc
index b33808e..13f5788 100644
--- a/src/main/asciidoc/reference-guide/workingwithapachesyncope/adminconsole/adminconsole.adoc
+++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/adminconsole/adminconsole.adoc
@@ -30,7 +30,7 @@ You should be greeted by the following web page.
[.text-center]
image::consoleLogin.png[console-login]
-You can use the <<changing-admin-password,default admin credentials>> to login.
+You can use the <<set-admin-credentials,default admin credentials>> to login.
==== Pages
http://git-wip-us.apache.org/repos/asf/syncope/blob/88602c0b/src/main/asciidoc/reference-guide/workingwithapachesyncope/customization.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/customization.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/customization.adoc
index 67f98e0..4d73273 100644
--- a/src/main/asciidoc/reference-guide/workingwithapachesyncope/customization.adoc
+++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/customization.adoc
@@ -63,6 +63,21 @@ endif::[]
This general behavior might have exceptions, as highlighted below.
====
+As a general way to operate, the Embedded Mode (see the
+ifeval::["{backend}" == "html5"]
+http://syncope.apache.org/docs/getting-started.html[Apache Syncope Getting Started Guide]
+endif::[]
+ifeval::["{backend}" == "pdf"]
+http://syncope.apache.org/docs/getting-started.pdf[Apache Syncope Getting Started Guide]
+endif::[]
+for details) allows to work comfortably from a single workstation, with no need of additional setup; such mode is
+effectively implemented as the `all`
+https://maven.apache.org/guides/introduction/introduction-to-profiles.html[Maven profile^], where the available optional
+components and extensions are enabled. +
+When deploying the generated WAR artifacts into an external <<javaee-container>> however, the required components and
+extensions need to be explicitly selected and enabled, as shown in the following.
+
+[[deployment-directories]]
.Deployment directories
****
Apache Syncope needs three base directories to be defined:
@@ -85,20 +100,6 @@ $ mkdir /opt/syncope/conf
....
****
-As a general way to operate, the Embedded Mode (see the
-ifeval::["{backend}" == "html5"]
-http://syncope.apache.org/docs/getting-started.html[Apache Syncope Getting Started Guide]
-endif::[]
-ifeval::["{backend}" == "pdf"]
-http://syncope.apache.org/docs/getting-started.pdf[Apache Syncope Getting Started Guide]
-endif::[]
-for details) allows to work comfortably from a single workstation, with no need of additional setup; such mode is
-effectively implemented as the `all`
-https://maven.apache.org/guides/introduction/introduction-to-profiles.html[Maven profile^], where the available optional
-components and extensions are enabled. +
-When deploying the generated WAR artifacts into an external <<javaee-container>> however, the required components and
-extensions need to be explicitly selected and enabled, as shown in the following.
-
The WAR artifacts are generated by running the Maven command (with reference to the suggested directory layout):
....
http://git-wip-us.apache.org/repos/asf/syncope/blob/88602c0b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/activitimodeler.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/activitimodeler.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/activitimodeler.adoc
new file mode 100644
index 0000000..4ab1e9d
--- /dev/null
+++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/activitimodeler.adoc
@@ -0,0 +1,46 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+==== Enable the Activiti Modeler
+
+Due to licensing issues - see
+https://issues.apache.org/jira/browse/SYNCOPE-439?focusedCommentId=13829896&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-13829896[this comment^]
+for more information - it is not possible to embed the
+http://www.activiti.org/components.html#modeler[Activiti Modeler^], which provides a powerful graphical web editing
+interface for Activiti BPM, into any Apache Syncope artifact; thus, some manual steps are required to enable it on a
+working Apache Syncope deployment, for use with the admin console.
+
+[WARNING]
+This procedure requires Apache Maven since it is using a fake project to perform all required setup tasks.
+
+First of all, generate a new Maven project as described in the
+ifeval::["{backend}" == "html5"]
+http://syncope.apache.org/docs/getting-started.html[Apache Syncope Getting Started Guide,]
+endif::[]
+ifeval::["{backend}" == "pdf"]
+http://syncope.apache.org/docs/getting-started.pdf[Apache Syncope Getting Started Guide,]
+endif::[]
+then build via
+
+....
+mvn -P all clean install
+....
+
+At this point, copy the `console/target/activiti-modeler/` directory in the desired location of the host where the
+admin console is deployed, then set the value of `activitiModelerDirectory` with such path in the `console.properties`
+file.
http://git-wip-us.apache.org/repos/asf/syncope/blob/88602c0b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/configurationparameters.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/configurationparameters.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/configurationparameters.adoc
new file mode 100644
index 0000000..f45973a
--- /dev/null
+++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/configurationparameters.adoc
@@ -0,0 +1,44 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+
+==== Configuration Parameters
+
+Most run-time configuration options are available as parameters and can be tuned either via the admin console, CLI or
+barely invoking the REST layer through http://curl.haxx.se/[curl^]:
+
+* `password.cipher.algorithm` - which cipher algorithm shall be used for encrypting password values; supported
+algorithms include `SHA-1`, `SHA-256`, `SHA-512`, `AES`, `S-MD5`, `S-SHA-1`, `S-SHA-256`, `S-SHA-512` and `BCRYPT`;
+salting options are available in the `security.properties` file;
+* `notificationjob.cronExpression` -
+http://www.quartz-scheduler.org/documentation/quartz-2.2.x/tutorials/crontrigger.html[cron^] expression describing how
+frequently the pending <<tasks-notification,notification tasks>> are processed: empty means disabled;
+* `notification.maxRetries` - how many times the delivery of a given notification should be attempted before giving up;
+* `token.length` - the length of the random tokens that can be generated as part of various <<workflow,workflow>>
+processes, including <<password-reset,password reset>>;
+* `token.expireTime` - the time after which the generated random tokens expire;
+* `selfRegistration.allowed` - whether self-registration (tipically via the enduser application) is allowed;
+* `passwordReset.allowed` - whether the <<password-reset,password reset>> feature (tipically via the enduser
+application) is allowed;
+* `passwordReset.securityQuestion` - whether the <<password-reset,password reset>> feature involves security questions;
+* `authentication.statuses` - the list of <<workflow,workflow>> statuses for which users are allowed to authenticate;
+* `log.lastlogindate` - whether the system updates the `lastLoginDate` field of users upon authentication;
+* `tasks.interruptMaxRetries` - how many attempts shall be made when interrupting a running <<task,task>>;
+* `return.password.value` - whether the hashed password value shall be returned when reading users.
+
+Besides this default set, new configuration parameters can be define to support <<customization,custom>> code.
http://git-wip-us.apache.org/repos/asf/syncope/blob/88602c0b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/configureconnidlocations.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/configureconnidlocations.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/configureconnidlocations.adoc
new file mode 100644
index 0000000..59eef00
--- /dev/null
+++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/configureconnidlocations.adoc
@@ -0,0 +1,72 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+==== Configure ConnId locations
+
+Apache Syncope can be configured for using either local and remote <<external-resources,connector bundles>>:
+
+* *local* connector bundles are located somewhere in the same filesystem where the Java EE container running
+Apache Syncope is deployed;
+* *remote* connector bundles are provided via Java or .NET
+https://connid.atlassian.net/wiki/display/BASE/Connector+Servers[connector server^].
+
+While local connector bundles feature an easy setup, remote connector bundles allow enhanced deployment scenarios and
+are particularly useful when it is needed to deal with architectural security constraints or when a connector bundle
+requires to run on a specific platform OS (say MS Windows) while Apache Syncope is deployed on another platform OS
+(say GNU/Linux).
+
+The `connid.properties` file holds the configuration for defining which ConnId locations (either local and remote)
+will be considered.
+
+The format is quite straightforward:
+
+....
+connid.locations=location1,\
+location2,\
+...
+locationN
+....
+
+where each location is the string representation of an URI of the form `file:/path/to/directory/` for local locations,
+`connid://key@host:port` for remote non-SSL connector servers or finally `connids://key@host:port[?trustAllcerts=true]`
+for remote SSL connector servers, with optional flag to disable certificate check. +
+
+.Single local location
+====
+....
+connid.locations=file:/opt/syncope/bundles/
+....
+====
+
+.Single remote location
+====
+....
+connid.locations=connid://sampleKey@windows2008:4554
+....
+====
+
+.Multiple locations
+====
+....
+connid.locations=file:/opt/syncope/bundles/,\
+file:/var/tmp/bundles/,\
+connid://sampleKey@windows2008:4554,\
+connids://anotherKey@windows2008:4559,\
+connids://aThirdKey@linuxbox:9001?trustAllCerts=true
+....
+====
http://git-wip-us.apache.org/repos/asf/syncope/blob/88602c0b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/connectorbundles.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/connectorbundles.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/connectorbundles.adoc
new file mode 100644
index 0000000..29b07f5
--- /dev/null
+++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/connectorbundles.adoc
@@ -0,0 +1,124 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+==== Install connector bundles
+
+<<external-resources,Connector bundles>> are made available as JAR files and can be configured, for a given deployment:
+
+* for Maven project, in local sources;
+* for all distributions, at run-time.
+
+===== Local sources
+
+====== Different version of predefined connector bundle
+
+First of all, verify which connector bundles are predefined in your project by looking at your project's parent
+ifeval::["{snapshotOrRelease}" == "release"]
+http://central.maven.org/maven2/org/apache/syncope/syncope/2.0.0-M4/{docVersion}[POM^].
+endif::[]
+ifeval::["{snapshotOrRelease}" == "snapshot"]
+https://repository.apache.org/content/groups/snapshots/org/apache/syncope/syncope/{docVersion}[POM^].
+endif::[]
+
+As you can see, there are several Maven properties on the form `connid.*.version`, controlling the related connector
+bundle's version.
+
+If you want your own project to use a different version of a given connector bundle, all you need to do is to override
+the related property in your own project's root pom.xml.
+
+Hence, supposing that you would like to use `net.tirasa.connid.bundles.db.table` version `2.2.5-SNAPSHOT` rather than
+`2.2.4` shipped with Apache Syncope, add the following property to your own project's root `pom.xml`:
+
+[source,xml]
+....
+<properties>
+ ...
+ <connid.database.version>2.2.5-SNAPSHOT</connid.database.version>
+</properties>
+....
+
+====== Non-predefined connector bundle
+
+If the needed connector bundle is not in the predefined set as shown above, you will need to add a new property into
+your own project's root `pom.xml`:
+
+[source,xml]
+....
+<properties>
+ ...
+ <my.new.connector.version>1.0.0</my.new.connector.version>
+</properties>
+....
+
+then change the `maven-dependency-plugin` configuration both in `core/pom.xml` and `console/pom.xml` from
+
+[source,xml]
+....
+<plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-dependency-plugin</artifactId>
+ <inherited>true</inherited>
+ <executions>
+ <execution>
+ <id>set-bundles</id>
+ <phase>process-test-resources</phase>
+ <goals>
+ <goal>copy</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin>
+....
+
+to
+
+[source,xml]
+....
+<plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-dependency-plugin</artifactId>
+ <inherited>true</inherited>
+ <configuration>
+ <artifactItems>
+ <artifactItem>
+ <groupId>my.new.connector.groupId</groupId>
+ <artifactId>my.new.connector.artifactId</artifactId>
+ <version>${my.new.connector.version}</version>
+ </artifactItem>
+ </artifactItems>
+ </configuration>
+ <executions>
+ <execution>
+ <id>set-bundles</id>
+ <phase>process-test-resources</phase>
+ <goals>
+ <goal>copy</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin>
+....
+
+===== Run-time
+
+Connector bundles can be added or replaced at run-time by performing the following steps:
+
+. https://github.com/Tirasa/ConnId/blob/master/README.md#available-connectors[Download^] the required connector bundle
+JAR file;
+. Copy the downloaded JAR file into one of configured <<configure-connid-locations,ConnId locations>>, typically the
+`bundles` directory where the other connector bundles are already available.
http://git-wip-us.apache.org/repos/asf/syncope/blob/88602c0b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/dbms.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/dbms.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/dbms.adoc
new file mode 100644
index 0000000..446a690
--- /dev/null
+++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/dbms.adoc
@@ -0,0 +1,152 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+==== DBMS
+
+===== PostgreSQL
+
+In `provisioning.properties`:
+
+....
+quartz.jobstore=org.quartz.impl.jdbcjobstore.PostgreSQLDelegate
+quartz.sql=tables_postgres.sql
+....
+
+In `domains/Master.properties` (for the `Master` domain):
+
+....
+Master.driverClassName=org.postgresql.Driver
+Master.url=jdbc:postgresql://localhost:5432/syncope
+Master.schema=
+Master.username=syncope
+Master.password=syncope
+Master.databasePlatform=org.apache.openjpa.jdbc.sql.PostgresDictionary
+Master.orm=META-INF/spring-orm.xml
+....
+
+[WARNING]
+This assumes that you have a PostgreSQL instance running on localhost, listening on its default port 5432 with a
+database `syncope` fully accessible by user `syncope` with password `syncope`.
+
+===== MySQL
+
+In `provisioning.properties`:
+
+....
+quartz.jobstore=org.quartz.impl.jdbcjobstore.StdJDBCDelegate
+quartz.sql=tables_mysql_innodb.sql
+....
+
+[WARNING]
+This assumes that the InnoDB engine is enabled in your MySQL instance - if this is not the case, then change the value
+for `quartz.sql` to `tables_mysql.sql`.
+
+In `domains/Master.properties` (for the `Master` domain):
+
+....
+Master.driverClassName=com.mysql.jdbc.Driver
+Master.url=jdbc:mysql://localhost:3306/syncope?characterEncoding=UTF-8
+Master.schema=
+Master.username=syncope
+Master.password=syncope
+Master.databasePlatform=org.apache.openjpa.jdbc.sql.MySQLDictionary(blobTypeName=LONGBLOB)
+Master.orm=META-INF/spring-orm.xml
+....
+
+[WARNING]
+This assumes that you have a MySQL instance running on localhost, listening on its default port 3306 with a database
+`syncope` fully accessible by user `syncope` with password `syncope`.
+
+===== MariaDB
+
+In `provisioning.properties`:
+
+....
+quartz.jobstore=org.quartz.impl.jdbcjobstore.StdJDBCDelegate
+quartz.sql=tables_mariadb_innodb.sql
+....
+
+[WARNING]
+This assumes that the InnoDB engine is enabled in your MriaDB instance - if this is not the case, then change the value
+for `quartz.sql` to `tables_mariadb.sql`.
+
+In `domains/Master.properties` (for the `Master` domain):
+
+....
+Master.driverClassName=org.mariadb.jdbc.Driver
+Master.url=jdbc:mariadb://localhost:3306/syncope?characterEncoding=UTF-8
+Master.schema=
+Master.username=syncope
+Master.password=syncope
+Master.databasePlatform=org.apache.openjpa.jdbc.sql.MariaDBDictionary
+Master.orm=META-INF/spring-orm.xml
+....
+
+[WARNING]
+This assumes that you have a MySQL instance running on localhost, listening on its default port 3306 with a database
+`syncope` fully accessible by user `syncope` with password `syncope`.
+
+===== Oracle Database
+
+In `provisioning.properties`:
+
+....
+quartz.jobstore=org.quartz.impl.jdbcjobstore.oracle.OracleDelegate
+quartz.sql=tables_oracle.sql
+....
+
+In `domains/Master.properties` (for the `Master` domain):
+
+....
+Master.driverClassName=oracle.jdbc.OracleDriver
+Master.url=jdbc:oracle:thin:@localhost:1521:orcl
+Master.schema=SYNCOPE
+Master.username=syncope
+Master.password=syncope
+Master.databasePlatform=org.apache.openjpa.jdbc.sql.OracleDictionary
+Master.orm=META-INF/spring-orm-oracle.xml
+....
+
+[WARNING]
+This assumes that you have an Oracle instance running on localhost, listening on its default port 1521 with a database
+`syncope` under tablespace `SYNCOPE`, fully accessible by user `syncope` with password `syncope`.
+
+===== MS SQL Server
+
+In `provisioning.properties`:
+
+....
+quartz.jobstore=org.quartz.impl.jdbcjobstore.MSSQLDelegate
+quartz.sql=tables_sqlServer.sql
+....
+
+In `domains/Master.properties` (for the `Master` domain):
+
+....
+Master.driverClassName=com.microsoft.sqlserver.jdbc.SQLServerDriver
+Master.url=jdbc:sqlserver://localhost:1344;database=syncope;selectMethod=cursor;sendStringParametersAsUnicode=false
+Master.schema=dbo
+Master.username=syncope
+Master.password=syncope
+Master.databasePlatform=org.apache.openjpa.jdbc.sql.SQLServerDictionary
+Master.orm=META-INF/spring-orm-sqlserver.xml
+....
+
+[WARNING]
+This assumes that you have a MS SQL Server instance running on localhost, listening on its default port 1344 with a
+database `syncope` fully accessible by user `syncope` with password `syncope`.
http://git-wip-us.apache.org/repos/asf/syncope/blob/88602c0b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/domainsmanagement.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/domainsmanagement.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/domainsmanagement.adoc
new file mode 100644
index 0000000..5c56152
--- /dev/null
+++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/domainsmanagement.adoc
@@ -0,0 +1,35 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+==== Domains Management
+
+<<domains>> are defined by three files in the <<properties-files-location,configuration directory>>; assuming
+that the domain name is `Two`, such files are:
+
+* `domains/TwoDomain.xml` - general configuration;
+* `domains/Two.properties` - for <<dbms>> parameters;
+* `domains/TwoContent.xml` - for content <<deal-with-internal-storage-export-import,initialization>>.
+
+When adding a new domain to an existing deployment it is possible to copy, rename and edit the files available for
+the `Master` dommain, always present.
+
+[CAUTION]
+Adding a new domain requires re-deploying the <<core>> application and restarting the Java EE container.
+
+Once a new domain is added, the admin credentials for such domain can be set via admin console, CLI or
+barely invoking the REST layer through http://curl.haxx.se/[curl^].
http://git-wip-us.apache.org/repos/asf/syncope/blob/88602c0b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/emailconfiguration.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/emailconfiguration.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/emailconfiguration.adoc
new file mode 100644
index 0000000..6001e51
--- /dev/null
+++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/emailconfiguration.adoc
@@ -0,0 +1,32 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+==== E-mail Configuration
+
+The `mail.properties` holds the configuration options to enable the effective delivery of <<notifications,notification>>
+e-mails:
+
+* `smtpHost` - the mail server host, typically an SMTP host;
+* `smtpPort` - the mail server port;
+* `smtpUser` - (optional) the username for the account at the mail host;
+* `smtpPassword` - (optional) the password for the account at the mail host;
+* `smtpProtocol` - the mail protocol;
+* `smtpEncoding` - the default encoding to use for MIME messages;
+* `smtpConnectionTimeout` - the connection timeout value in milliseconds, to the mail host;
+* `mailDebug` - when `true`, enable the debugging of email, including the handshake, authentication, delivery and
+disconnection.
http://git-wip-us.apache.org/repos/asf/syncope/blob/88602c0b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/highavailability.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/highavailability.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/highavailability.adoc
new file mode 100644
index 0000000..0398d99
--- /dev/null
+++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/highavailability.adoc
@@ -0,0 +1,52 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+==== High-Availability
+
+When deploying multiple Apache Syncope instances insisting on a single database or database cluster, it is of
+fundamental importance that the contained OpenJPA instances are correctly configured for
+http://openjpa.apache.org/builds/2.4.1/apache-openjpa/docs/ref_guide_event.html[remote event notification^]. +
+Such configuration, in fact, allows the OpenJPA data cache to remain synchronized when deployed in multiple JVMs, thus
+enforcing data consistency across all Apache Syncope instances.
+
+The default configuration in `domains.xml` is
+
+[source,xml]
+....
+<entry key="openjpa.RemoteCommitProvider" value="sjvm"/>
+....
+
+which is suited for single JVM installations; with multiple instances, more options like as TCP or JMS are available;
+see the OpenJPA documentation for reference.
+
+[WARNING]
+====
+The OpenJPA documentation refers to direct configuration under `META-INF/persistence.xml`; for example:
+
+[source,xml]
+....
+<property name="openjpa.RemoteCommitProvider" value="tcp(Addresses=10.0.1.10;10.0.1.11)"/>
+....
+
+while for use in `domains.xml`, this becomes:
+
+[source,xml]
+....
+<entry key="openjpa.RemoteCommitProvider" value="tcp(Addresses=10.0.1.10;10.0.1.11)"/>
+....
+====
http://git-wip-us.apache.org/repos/asf/syncope/blob/88602c0b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/importexport.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/importexport.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/importexport.adoc
new file mode 100644
index 0000000..024ec63
--- /dev/null
+++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/importexport.adoc
@@ -0,0 +1,83 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+==== Deal with internal storage export - import
+
+Almost every configurable aspect of a given deployment is contained into the <<persistence,internal storage>>:
+schemas, connectors, resources, mapping, roles, groups, tasks and other parameters.
+
+During the implementation phase of an Apache Syncope-based project, it might be handful to move such configuration back
+and forth from one Apache Syncope instance to another (say developer's laptop and production server). +
+An option is clearly acting at low level by empowering DBMS' dump & restore capabilities, but what if developer is
+running MySQL (or even in-memory H2) while sysadmin features Oracle?
+
+[CAUTION]
+.Wipe existing content
+=====
+When not running in-memory H2, the internal storage's content must be wiped before starting Apache Syncope, otherwise
+the provided content will be just ignored.
+
+Check `core-persistence.log` for message
+
+....
+Empty database found, loading default content
+....
+
+If the internal storage is not empty, instead, you will get
+
+....
+Data found in the database, leaving untouched
+....
+=====
+
+[WARNING]
+=====
+All references in the following are set to `MasterContent.xml`; when other <<domains,domains>> are defined, the content
+file is renamed accordingly. For example, `TwoContent.xml` if domain name is `Two`.
+=====
+
+[WARNING]
+.MySQL and lower case table names
+=====
+On some platforms (namely, Mac OS X) MySQL is configured by default to be case insensitive: in such cases, you might
+want to edit the `/etc/my.cnf` file and add the following line in the `[mysqld]` section:
+
+....
+lower_case_table_names=1
+....
+=====
+
+===== Export
+
+This task can be accomplished either via admin console, CLI or by barely invoking the REST layer through
+http://curl.haxx.se/[curl^], for example:
+
+....
+curl -X GET -u admin:password -o MasterContent.xml \
+ http://localhost:9080/syncope/rest/configurations/stream
+....
+
+===== Import
+
+Basically, all you need to do is to replace the local `MasterContent.xml` with the one exported as explained above; but
+where such file located?
+
+* `$TOMCAT_HOME/webapps/syncope/WEB-INF/classes/domains/MasterContent.xml` for Standalone
+* `/usr/share/tomcat8/webapps/syncope/WEB-INF/classes/domains/MasterContent.xml` for Debian packages
+* `core/src/test/resources/domains/MasterContent.xml` for Maven projects in embedded mode
+* `core/src/main/resources/domains/MasterContent.xml` for Maven projects
http://git-wip-us.apache.org/repos/asf/syncope/blob/88602c0b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/javaeecontainer.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/javaeecontainer.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/javaeecontainer.adoc
new file mode 100644
index 0000000..c9a7ee0
--- /dev/null
+++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/javaeecontainer.adoc
@@ -0,0 +1,113 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+==== JavaEE Container
+
+===== Apache Tomcat 8 and 8.5
+
+On GNU / Linux - Mac OS X, create `$CATALINA_HOME/bin/setenv.sh` with similar content
+(keep everything on a single line):
+
+....
+JAVA_OPTS="-Djava.awt.headless=true -Dfile.encoding=UTF-8 -server \
+-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m \
+-XX:MaxPermSize=256m -XX:+DisableExplicitGC"
+....
+
+On MS Windows, create `%CATALINA_HOME%\bin\setenv.bat` with similar content (keep everything on a single line):
+
+....
+set JAVA_OPTS=-Djava.awt.headless=true -Dfile.encoding=UTF-8 -server
+-Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m
+-XX:MaxPermSize=256m -XX:+DisableExplicitGC
+....
+
+It is recommended to define a separate datasource for each <<domains,domain>> (the following example is for the `Master`
+domain and MySQL): please also check that the connection parameters are the same as configured for <<dbms>>:
+
+[source,xml]
+....
+<Resource name="jdbc/MasterDataSource" auth="Container" type="javax.sql.DataSource"
+ factory="org.apache.tomcat.jdbc.pool.DataSourceFactory" testWhileIdle="true"
+ testOnBorrow="true" testOnReturn="true" validationQuery="SELECT 1" validationInterval="30000"
+ maxActive="100" minIdle="2" maxWait="10000" initialSize="2" removeAbandonedTimeout="20000"
+ removeAbandoned="true" logAbandoned="true" suspectTimeout="20000"
+ timeBetweenEvictionRunsMillis="5000" minEvictableIdleTimeMillis="5000"
+ jdbcInterceptors="org.apache.tomcat.jdbc.pool.interceptor.ConnectionState;
+ org.apache.tomcat.jdbc.pool.interceptor.StatementFinalizer"
+ username="syncope" password="syncope" driverClassName="com.mysql.jdbc.Driver"
+ url="jdbc:mysql://localhost:3306/syncope?characterEncoding=UTF-8"/>
+....
+
+[CAUTION]
+Be sure to put the corresponding JDBC driver JAR file under `$CATALINA_HOME/lib` for each datasource defined.
+
+===== Glassfish 4.1 and Payara Server
+
+When using a datasource for internal storage, be sure to add
+
+[source,xml]
+....
+<resource-ref>
+ <res-ref-name>jdbc/MasterDataSource</res-ref-name>
+ <jndi-name>jdbc/MasterDataSource</jndi-name>
+</resource-ref>
+....
+
+right after `</context-root>` in `core/src/main/webapp/WEB-INF/glassfish-web.xml`, assuming that your Glassfish instance
+provides a datasource named `jdbc/MasterDataSource`.
+
+===== Wildfly 9 and 10
+
+Replace
+
+....
+ classpath*:/*Context.xml
+....
+
+with
+
+....
+ classpath*:/*Context.xml
+ /WEB-INF/classes/restCXFContext.xml
+....
+
+in `core/src/main/webapp/WEB-INF/web.xml`.
+
+Download
+ifeval::["{snapshotOrRelease}" == "release"]
+https://github.com/apache/syncope/blob/syncope-{docVersion}/fit/core-reference/src/main/resources/jboss/restCXFContext.xml[restCXFContext.xml^]
+endif::[]
+ifeval::["{snapshotOrRelease}" == "snapshot"]
+https://github.com/apache/syncope/blob/master/fit/core-reference/src/main/resources/jboss/restCXFContext.xml[restCXFContext.xml^]
+endif::[]
+and save it under `core/src/main/resources/`.
+
+Finally, add
+
+[source,xml]
+....
+<property name="jpaPropertyMap">
+ <map>
+ <entry key="openjpa.MetaDataFactory"
+ value="jpa(URLs=vfs:/content/${project.build.finalName}.war/WEB-INF/classes, Resources=${Master.orm})"/>
+ </map>
+</property>
+....
+
+in `core/src/main/resources/domains/MasterDomain.xml` for the `MasterEntityManagerFactory` bean.
http://git-wip-us.apache.org/repos/asf/syncope/blob/88602c0b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/setadmincredentials.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/setadmincredentials.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/setadmincredentials.adoc
new file mode 100644
index 0000000..4292a06
--- /dev/null
+++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/setadmincredentials.adoc
@@ -0,0 +1,49 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+==== Set admin credentials
+
+[WARNING]
+The procedure below affects only the `Master` <<domains,domain>>; for other domains check <<domains-management,above>>.
+
+The default password for the `admin` user is `password`.
+
+The credentials are defined in the `security.properties` file; text encoding must be set to UTF-8:
+
+* `adminUser` - administrator username
+* `adminPassword` - SHA1 hash evaluation of cleartext password (represented as a sequence of 40 hexadecimal digits)
+* `adminPasswordAlgorithm` - algorithm to be used for hash evaluation (default value: SHA1)
+
+For GNU / Linux and Mac OS X, the SHA1 password can be obtained via the `sha1sum` command-line tool of
+http://www.gnu.org/software/coreutils/[GNU Core Utilities^]:
+
+[source,bash]
+....
+echo -n "new_password" | sha1sum
+....
+For MS Windows, some options are available:
+
+* http://support.microsoft.com/kb/841290[MS File Checksum Integrity Verifier^] +
+install, save your password to a file (e.g. `password.txt` without EOL) and issue at command line: +
+[source,bash]
+....
+fciv.exe -sha1 password.txt
+....
+* http://gnuwin32.sourceforge.net/[GnuWin32^] port of GNU utilities for MS Windows
+* http://www.cygwin.com/[Cygwin^] Unix-like environment and command-line interface for Microsoft Windows (featuring
+http://www.gnu.org/software/coreutils/[GNU Core Utilities^])
http://git-wip-us.apache.org/repos/asf/syncope/blob/88602c0b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/systemadministration.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/systemadministration.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/systemadministration.adoc
new file mode 100644
index 0000000..302b1e3
--- /dev/null
+++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/systemadministration.adoc
@@ -0,0 +1,73 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+=== System Administration
+
+[[properties-files-location]]
+.Where are the configration files?
+****
+Depending on which Apache Syncope distribution you are running on, the configuration files mentioned in the following
+might reside in different locations.
+
+Standalone:: Assuming that `$CATALINA_HOME` is the Apache Tomcat base directory created when the distribution archive
+was unzipped, the configuration files are located under
+
+* `$CATALINA_HOME/webapps/syncope/WEB-INF/classes/`
+* `$CATALINA_HOME/webapps/syncope-console/WEB-INF/classes/`
+* `$CATALINA_HOME/webapps/syncope-enduser/WEB-INF/classes/`
+
+Debian packages:: The configuration files will be fist searched in `/etc/apache-syncope`, then under
+
+* `/usr/share/tomcat8/webapps/syncope/WEB-INF/classes/`
+* `/usr/share/tomcat8/webapps/syncope-console/WEB-INF/classes/`
+* `/usr/share/tomcat8/webapps/syncope-enduser/WEB-INF/classes/`
+
+GUI installer:: Assuming that `$CONF_DIRECTORY` is the one selected from installer, the configuration files will be fist
+searched in `$CONF_DIRECTORY`, then under the selected Java EE container's application classpath.
+
+Maven project:: Assuming that `$CONF_DIRECTORY` is the one passed among
+<<deployment-directories,deployment directories>> at build time and that `$SOURCE` is the path where the Maven project
+was generated, the configuration files will be fist searched in
+`$CONF_DIRECTORY`, then under the selected Java EE container's application classpath, according to the content of
+
+* `$SOURCE/core/target/classes/`
+* `$SOURCE/console/target/classes/`
+* `$SOURCE/enduser/target/classes/`
+****
+
+include::dbms.adoc[]
+
+include::javaeecontainer.adoc[]
+
+include::highavailability.adoc[]
+
+include::domainsmanagement.adoc[]
+
+include::setadmincredentials.adoc[]
+
+include::configureconnidlocations.adoc[]
+
+include::importexport.adoc[]
+
+include::activitimodeler.adoc[]
+
+include::connectorbundles.adoc[]
+
+include::emailconfiguration.adoc[]
+
+include::configurationparameters.adoc[]
http://git-wip-us.apache.org/repos/asf/syncope/blob/88602c0b/src/main/asciidoc/reference-guide/workingwithapachesyncope/workingwithapachesyncope.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/workingwithapachesyncope.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/workingwithapachesyncope.adoc
index 488ec9e..7b6f69e 100644
--- a/src/main/asciidoc/reference-guide/workingwithapachesyncope/workingwithapachesyncope.adoc
+++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/workingwithapachesyncope.adoc
@@ -38,20 +38,4 @@ include::restfulservices.adoc[]
include::customization.adoc[]
-=== Deploying in production
-
-==== DBMS
-
-==== JavaEE Container
-
-==== High-Availability
-
-=== Runtime Management
-
-==== Configuration Parameters
-
-==== Domains Management
-
-==== HowTOs
-
-===== Changing admin password
+include::systemadministration/systemadministration.adoc[]