The entire "Administration and Configuration Guide" migrated from wiki.

docs/concepts/system-configuration-object.adoc

@@ -0,0 +1,27 @@
+= System Configuration Object
+:page-wiki-name: System Configuration Object
+:page-upkeep-status: orange
+
+System Configuration object is a midPoint object that represents global system configuration applicable for the system itself, logging, profiling, all the resources, tasks, processes and all other aspects of the system.
+There is usually just one system configuration object.
+It has fixed wiki:Object+ID[OID]`00000000-0000-0000-0000-000000000001`.
+
+
+== Example
+
+[source,xml]
+----
+<systemConfiguration oid="00000000-0000-0000-0000-000000000001">
+    <name>SystemConfiguration</name>
+    <logging>
+        <rootLoggerAppender>File Appender</rootLoggerAppender>
+        <rootLoggerLevel>INFO</rootLoggerLevel>
+        <appender xsi:type="FileAppenderConfigurationType" name="File Appender" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+            <pattern>%date [%thread] %-5level \(%logger{46}\): %message%n</pattern>
+            <fileName>target/test.log</fileName>
+            <append>true</append>
+        </appender>
+    </logging>
+</systemConfiguration>
+----
+

docs/deployment/clustering-ha/managing-cluster-nodes.adoc

@@ -0,0 +1,198 @@
+= Managing cluster nodes
+:page-wiki-name: Managing cluster nodes
+:page-since: [ "4.1", "4.0.2" ]
+
+// also available in 4.0.2
+
+
+MidPoint can run in clustered mode with two or more nodes.
+Here we describe the most important parameters influencing how nodes are named and managed.
+
+
+== Node identification (naming)
+
+Each node in cluster must have a unique node identifier (name).
+
+
+=== nodeId vs. nodeIdSource
+
+There are two properties that can be used to set the node identifier:
+
+[%autowidth]
+|===
+| Property | Meaning | Placement | Alternative specification | Examples
+
+| `nodeId`
+| A constant value or an expression that yields the node name
+| `<midpoint>`  section in `config.xml`
+| `-Dmidpoint.nodeId`  command line parameter
+| `NodeA`, `${env:NodeID}`
+
+
+| `nodeIdSource`
+| Mechanism that is used to derive node Id (obsolete)
+| `<midpoint>`  section in `config.xml`
+| `-Dmidpoint.nodeIdSource`  command line parameter
+| `hostname`, `random`, `sequence`
+
+
+|===
+
+The `nodeIdSource` was originally meant as a way to assign node identifiers without the need to specify them as constants.
+However, after `nodeId` started supporting expressions, `nodeIdSource`  is now simply translated into `nodeId`.
+
+[TIP]
+====
+The translation looks like this:
+
+* if `nodeIdSource`  value contains ':' (e.g. it is `random:number:0:9999`) then it is copied into `nodeId` by wrapping in `${...}`. For example:  `random:number:0:9999`  ${`random:number:0:9999}`
+
+* if `nodeIdSource`  value does not contain ':' (e.g. it is `hostname`) then it is copied into `nodeId`  by wrapping in `${...}` with appended colon at the end.
+For example:  `hostname`` ${hostname:}`
+
+====
+
+So, let's deal with the syntax of `nodeId`  only in the following discussion.
+
+
+=== Using nodeId property
+
+Since 4.0.2/4.1, midPoint configuration properties support expressions in the form of `${variable}` or `${prefix:variable}`. The first form evaluates using a configuration option specified by `variable`. The second one is more general and supports the following prefixes:
+
+[%autowidth]
+|===
+| Prefix | Meaning | Example
+
+| `sys`
+| References given Java system properties.
+| `${sys:user.home}`
+
+
+| `env`
+| References given operating system environment variables.
+| `${env:ENVIRONMENT}`
+
+
+| `hostname`
+| References local host name as determined by midPoint.
+Note that the colon after hostname is obligatory.
+| `${hostname:}`
+
+
+| `random`
+| Generates random node ID.
+Full format is `${random:number:lower-limit:upper-limit}` but accepts also forms of `${random:}`, `${random:number}`, and `${random:number:upper-limit}`. Default values are lower limit = 0, upper limit = 999999999.
+Lower and upper limits are inclusive.
+| `${random:}`
+
+
+| `sequence`
+| Uses first available node ID in a given sequence.
+Full format is `${sequence:start:end:format}` but accepted forms are also `${sequence:}`, `${sequence:start}`, and `${sequence:start:end}`. Default values are: start = 0, end = 100, format = %d.
+| `${sequence:0:99:%02d}`
+
+
+|===
+
+The `sequence` expression works like this:
+
+. A counter starts at the `start` value, incrementing by 1 up to (and including) the `end` value.
+
+. At each step, node name is determined using the formatting string and other parts of the expression, and is checked for availability.
+
+. If such a node does not exist in the repository, the name is used.
+Technically speaking, the node name is allocated by creating the node in the repository.
+If the operation succeeds, the node is acquired.
+This is to avoid race conditions: only the first midPoint instance that successfully creates a node object can use this name.
+
+. If a node with a given name exists but the node is permanently down (this is determined by `running` property being set to `false`) the name is used.
+This is implemented by removing the node object and then retrying the allocation attempt.
+
+. Names of nodes that are not marked as down but are not alive are *not* used here.
+This is to avoid using names of nodes that are e.g. currently booting, or temporarily unavailable.
+Please see the Node state management section below.
+
+Note that `sequence`  expression can be combined with other ones.
+E.g. you can specify `nodeId` as `${env:ENVIRONMENT}-${sequence:0:99:%02d}`, yielding names like `Test-01`, `Test-02`, ..., `QA-01`, `QA-02`, ..., `Prod-01`, `Prod-02`, ...
+
+
+== Node state management
+
+A midPoint node can be typically in one of the following states:
+
+[%autowidth]
+|===
+| State | Characterization
+
+| up and alive
+| Node regularly checks into the repository.
+Its `operationalState`  property is `UP` and its `lastCheckInTime` is regularly updated (less than `nodeTimeout` ago).
+
+
+| up, but not checking in
+| There's an issue with this node.
+Its `operationalState`  property is `UP` but its `lastCheckInTime` is older than `nodeTimeout` seconds.
+Nodes in this state are excluded from some operations e.g. status querying or cache invalidation calls.
+
+
+| down
+| Node's `operationalState` property is `DOWN`. This typically occurs when the node is going down cleanly: it marks itself as down.
+If node goes down abruptly (without having a chance to do this modification), other nodes watch its `lastCheckInTime` and after it's older than `nodeAlivenessTimeout` ago, they mark the respective node as down by setting its `operationalState` property to `DOWN`. This check is occurring every `nodeAlivenessCheckInterval` seconds.
+Nodes in this state are excluded from almost all operations.
+
+
+| starting
+| Node's `operationalState`  property is `STARTING`. Nodes in this state are excluded from some operations e.g. status querying or cache invalidation calls.
+
+
+| deleted
+| Node object no longer exists in the repository.
+The deletion can occur either manually or by the Cleanup task.
+The task deletes nodes that have `lastCheckInTime` older than `deadNodes/maxAge` ago.
+
+
+|===
+
+Default parameter values:
+
+[%autowidth]
+|===
+| Parameter | Where it is | Description | Default value
+
+| `nodeTimeout`
+| `taskManager` section of `config.xml`
+| When to start considering node as not checked in.
+| 30 seconds
+
+
+| `nodeAlivenessTimeout`
+| `taskManager` section of `config.xml`
+| When to start considering node as being down.
+| 900 seconds
+
+
+| `nodeAlivenessCheckInterval`
+| `taskManager` section of `config.xml`
+| How often is the node aliveness check carried out.
+| 120 seconds
+
+
+| `nodeStartupTimeout`
+| `taskManager` section of `config.xml`
+| When to start reporting node as starting too long.
+| 900 seconds
+
+
+| `deadNodes/maxAge`
+| cleanup policy e.g. in the system configuration object
+| After what not-checked-in time should the node be deleted.
+| none
+
+
+|===
+
+ The nodes are not cleaned up by default.
+If you'd like to enable this feature, you can set this parameter to e.g. 1 day.
+Note that cleanup task runs - by default - once per day.
+But you can change this interval or you can schedule other cleanup task, devoted specifically to cleaning up dead nodes.
+

docs/deployment/concepts/index.adoc

@@ -0,0 +1,132 @@
+= Deployment Concepts
+:page-wiki-name: Deployment Concepts
+:page-upkeep-status: red
+:page-toc: top
+
+
+== Introduction
+
+Simply speaking midPoint is a Java web application.
+It is delivered in a single WAR archive and all that is needed for running it is to use appropriate tool to deploy it to the web container.
+An external database is usually needed so it also needs to be configured.
+But that's basically all what you need.
+This minimal deployment is illustrated in the following diagram.
+
+image::Basic-Deployment.png[]
+
+The diagram illustrates the following scenario: MidPoint is a web application that is deployed in a web container.
+The web container is Apache Tomcat in this case and it runs on a dedicated server.
+MidPoint is configured to use external relational database that runs on a separate server.
+MidPoint is configured to connect to two resources.
+MidPoint administrators are accessing the web-based administration console directly on the midPoint instance.
+
+[TIP]
+.Color Code
+====
+All the diagrams use similar color code.
+The shades of yellow, orange and brown are used for parts of the code midPoint installation.
+Blue colors are used for standard infrastructure components, standard protocol and interfaces and so on.
+Green is used to denote the integrated systems (resources), custom component, etc.
+====
+
+But the devil is in the detail and there are many alternative configurations that can be used for midPoint deployment.
+Following sections will provide detailed information about deployment alternatives.
+
+
+== Repository
+
+MidPoint needs a database to store its own data.
+This includes data about users, accounts and links, policies and also a configuration such as resource definitions.
+Although midPoint comes with an embedded database engine this is not supposed to be used for a production environment.
+Therefore an external SQL database is usually needed for most midPoint deployments.
+
+Most of midPoint configuration is stored in the database.
+However for obvious reasons the database configuration needs to be outside the database.
+It is stored in the `config.xml` file in wiki:MidPoint+Home+Directory[midPoint home directory]. The wiki:Repository+Configuration[Repository Configuration] page describes the configuration of database access.
+
+
+== Connectors
+
+Connectors are midPoint workhorses.
+They provide connectivity to target and source systems that are called _resources_ in midPoint terminology.
+Connectors are usually quite short and simple pieces of code that needs to be "deployed" to midPoint.
+The deployment is usually just copy of the connector package to the appropriate directory and restarting midPoint.
+The wiki:Connector+Deployment[Connector Deployment] page provides all the details.
+
+image::Complex-Deployment.png[]
+
+Connectors are usually written in Java and are distributed as a JAR files.
+Such connectors may be used inside midPoint by deploying them directly to midPoint instance.
+This is the usual case.
+Some of the frequently-used connectors are also bundled directly with midPoint to ease the deployment process.
+MidPoint has the ability to use several versions of the same connector at once which is useful for slowly testing and rolling out new connector versions.
+See wiki:Connector+Upgrade[Connector Upgrade] page for more details.
+
+
+=== Remote Connector Server
+
+Connectors sometimes need to be placed on different servers than that the midPoint is using.
+One of the reasons may be that the connector needs platform and/or libraries that are not available from midPoint, e.g. Microsoft proprietary libraries.
+Other reason might be that the connector needs local access to resources that reside on other servers, e.g. access to local files.
+Whatever the reason might be there is an option to run connectors over the network.
+The component that allows that is _Remote Connector Server_. There are two implementations of Remote Connector Server.
+One is using Java platform, the second uses .NET Framework.
+
+See link:http://wiki.evolveum.com/display/midPoint/Connector+Server[Connector Server] page for more details.
+
+
+==== Java Remote Connector Server
+
+Java Remote Connector Server is using the same kind of connectors as midPoint is using itself.
+The Java Remote Connector Server is used in situations where a connector needs a local access to some resource.
+Otherwise is not able to work with it.
+It is usually used for connectors that require local access to files such as link:http://wiki.evolveum.com/display/midPoint/CSVFile+Connector[CSVFile Connector]. This approach avoids the need to copy the file using FTP or a similar mechanism which is difficult to do in a proper way and it is quite error-prone (e.g. problems with partially downloaded files, error handling, atomicity, etc.) Java Remote Connector Server is also used in situations that require firewall traversal or securing insecure communication protocol.
+
+image::Connector-Server-Deployment.png[]
+
+See wiki:Java+Connector+Server[Java Connector Server] page for more details and for installation instructions.
+
+==== .NET Remote Connector Server
+
+.NET Remote Connector Server is a wiki:Connector+Server[Connector Server] that runs on Windows machines using the .NET framework.
+Perhaps the only practical purpose of this connector server is to provide environment for Windows-specific connectors.
+Connectors such as wiki:Legacy+Active+Directory+Connector+(.NET)[Legacy Active Directory Connector (.NET)] require proprietary libraries that are only available on Microsoft platforms (.NET) and cannot be used from Java.
+Therefore midPoint cannot use such libraries in a local connector (or remote Java connector for that matter) and a .NET-based remote connector server is required.
+
+image::Remote-Connector-Server-Deployment.png[]
+
+
+
+See wiki:.NET+Connector+Server[.NET Connector Server] page for more details and for installation instructions.
+
+== Reverse Proxy
+
+TODO
+
+
+== High Availability
+
+TODO
+
+
+== Keystore
+
+TODO
+
+See also link:http://wiki.evolveum.com/display/midPoint/Encryption+and+Keys#Keystore[here].
+
+
+== Recommendations
+
+TODO: use existing database +
+ TODO: do not deploy midPoint with other complex applications in the same container +
+ TODO: works well in virtual environment +
+ TODO: use Sun Java JDK/JRE +
+ TODO: Tomcat is a recommended container (lightweight, opensource, well tested).
+Use apache as reverse proxy for flexibility.
+
+
+== See Also
+
+TODO
+