ninja: docs improvements, wip

(cherry picked from commit 210f371)

docs/deployment/ninja/command/count.adoc

@@ -0,0 +1,11 @@
+= Count
+
+Count command counts objects in midPoint repository.
+It can count all objects or objects filtered by type (`-t, --type`) and filter (`-f, --filter`).
+Result is printed to `SYSOUT` separately for each object type and total count.
+
+.Example of counting all objects in the repository
+[source,bash]
+----
+./bin/ninja.sh count
+----

docs/deployment/ninja/command/delete.adoc

@@ -0,0 +1,9 @@
+= Delete
+
+Delete command deletes objects from midPoint repository.
+Objects which should be deleted can be filtered in several ways:
+
+* by oid (`--oid`)
+* type (`-t, --type`) and filter (`-f, --filter`)
+
+Additionally, there is option to confirm each delete operation (`-a`, `--ask`).

docs/deployment/ninja/command/download-distribution.adoc

@@ -0,0 +1,30 @@
+= Download distribution
+
+Download distribution is simple step that helps you download specific version of distribution of midPoint.
+Midpoint distribution is downloaded from https://download.evolveum.com/midpoint/[download.evolveum.com].
+
+By default, next version of midPoint is downloaded based on current version.
+E.g. for feature release 4.7.1, next version is 4.8 and for LTS upgrade from 4.4.6 ninja will download 4.8 as well.
+
+Version which should be downloaded can be specified using `--distribution-version` option.
+Use `latest` to specify latest build to be downloaded (at the time of writing it's `4.8-SNAPSHOT`).
+
+User can also provide custom build downloaded or built separately (e.g. using maven overlay) using switch `--distribution-archive <PATH_TO_ZIP>`.
+This switch is useful mainly in compound command `upgrade-distribution` where user can use distribution located on filesystem without need to download it.
+
+.Example of how to download distribution (default next version based on the current midPoint)
+[source,bash]
+----
+./bin/ninja.sh download-distribution \
+  --temp-dir .upgrade \
+  --distribution-directory .upgrade/new-distribution
+----
+
+.Example on how to download specific version of distribution (latest snapshot)
+[source,bash]
+----
+./bin/ninja.sh download-distribution \
+  --temp-dir .upgrade \
+  --distribution-directory .upgrade/latest-distribution \
+  --distribution-version latest
+----

docs/deployment/ninja/command/export-audit.adoc

@@ -0,0 +1,25 @@
+= Export audit
+
+#TODO split into export and import#
+
+[NOTE]
+Audit export/import uses the same format as objects, even utilizing `<objects>` element,
+but audit records are *containers, not objects*.
+These files are only useful for Ninja import/export, do not try to use them in Studio or otherwise.
+
+.Example: audit export to a zipped file, overwriting any existing file, using an Axiom filter
+[source,bash]
+----
+ninja.sh exportAudit -o audit-export.xml.zip -z -O -f '%timestamp < "2021-12-01"'
+----
+
+Now you can move the exported file to a new environment and run the import:
+
+.Example: audit import
+[source,bash]
+----
+ninja.sh importAudit -i audit-export.xml.zip -z
+----
+
+Check also the xref:/midpoint/reference/repository/native-audit/#audit-migration-from-other-database[migration guide for the Native audit].
+

docs/deployment/ninja/command/export-mining.adoc

@@ -0,0 +1,49 @@
+= Export mining
+
+[NOTE]
+Role mining export is an anonymized export of relationships between roles, users, and
+organizations. The goal of the export is to obtain a map of relations between objects, which could
+be helpful in the development of new features such as "Role mining".
+For detailed information regarding role mining export, please refer to the
+xref:/midpoint/reference/roles-policies/mining/anonymous-data-export/#anonymous-export-of-role-mining-data[Anonymous Export of Role Mining Data].
+
+.Example: role mining export to a `zipped` file, `overwriting` any existing file. `SEQUENTIAL` name mode and `ADVANCED` security by default. For exporting in JSON format, rename the exported file extension to `-o role-mining-export.json`.
+[source,bash]
+----
+ninja.sh export-mining -o role-mining-export.xml.zip -z -O
+----
+
+----
+java -jar ninja.jar -m <midpoint.home> export-mining -o role-mining-export.xml.zip -z -O
+
+----
+
+.Example: role mining export using `ENCRYPTED` name mode and  `STANDARD` security.
+[source,bash]
+----
+ninja.sh export-mining -o role-mining-export.xml.zip -z -O -nm ENCRYPTED -s STANDARD
+----
+
+.Example: role mining export using an `Axiom filter` for roles.
+[source,bash]
+----
+ninja.sh export-mining -o role-mining-export.xml -fr '% name != "Superuser"'
+----
+
+.Example: role mining export using `ORIGINAL` name mode, identifiers Application and Business role `prefixes/suffixes` and specific `archetypes oids`.
+[source,bash]
+----
+ninja.sh export-mining -o role-mining-export.xml  -nm ORIGINAL -arp "APP_ROLE_, AR-" -ars "_Apr" -brp "BUS_ROLE_" -brs "_BR" --business-role-archetype-oid "e9c4654e-c146-4b5f-8336-2065c65060df" --application-role-archetype-oid "52b8361a-c955-4132-97a4-77ff3820beeb"
+----
+
+.Example: role mining export with `disable organization` structure export.
+[source,bash]
+----
+ninja.sh export-mining -o role-mining-export.xml --disable-org
+----
+
+.Example: role mining import.
+[source,bash]
+----
+java -jar ninja.jar -m <midpoint.home> import -O -i <path_to_imported_file> -l 4 -r
+----

docs/deployment/ninja/command/export.adoc

@@ -0,0 +1,21 @@
+= Export
+
+Export command allows users to export objects.
+Object can be exported to `SYSOUT` or to file (`-o`, `--output`) and compressed using ZIP if needed (`-z`, `--zip`).
+Export also support multi-threading (`-l`, `--multi-thread`).
+Use `-O`, `--overwrite` switch if you wish to overwrite an existing output file.
+Objects exported from midPoint can be filtered in several ways:
+
+* by oid (`--oid`)
+* by type (`-t, --type`) and filter (`-f, --filter`)
+
+[WARNING]
+When exporting shadow objects from midPoint `-r (--raw)` option must be used to export data correctly.
+Raw option will add schema for shadow attributes (to be used in import later on).
+Behavior without raw option will export shadow attribute without schema because of backward compatibility.
+
+.Example of export to compressed zip file using 4 threads:
+[source,bash]
+----
+./bin/ninja.sh export -O export.zip -z -l 4
+----

docs/deployment/ninja/command/help.adoc

@@ -0,0 +1,18 @@
+= Help
+
+Help command prints help for specific command or all commands.
+When printing help for all commands, it will print general option and lists all commands.
+
+.Example of printing help for all commands
+[source,bash]
+----
+./bin/ninja.sh help
+----
+
+When printing help for specific command, it will also print usage and all options for that command.
+
+.Example of printing help for specific command
+[source,bash]
+----
+./bin/ninja.sh help export
+----

docs/deployment/ninja/command/import-audit.adoc

@@ -0,0 +1,3 @@
+= Import audit
+
+#TODO#

docs/deployment/ninja/command/import.adoc

@@ -0,0 +1,16 @@
+= Import
+
+Import command allow users to import objects to midPoint.
+Objects can be read from `SYSOUT` or file (`-i`, `--input`) and uncompressed using ZIP if needed (`-z`, `--zip`).
+Import also support multi-threading (`-l`, `--multi-thread`).
+Use `-O`, `--overwrite` switch if you wish to overwrite existing objects in midPoint.
+Object read from input (file or sysout) can be filtered in several ways:
+
+* by oid (`--oid`)
+* by type (`-t, --type`) and filter (`-f, --filter`)
+
+.Example of import from XML file using 4 threads with raw and overwrite option
+[source,bash]
+----
+./bin/ninja.sh import -O -i midpoint/samples/objects/user-ceresnickova.xml -l 4 -r
+----

docs/deployment/ninja/command/index.adoc

@@ -0,0 +1 @@
+:page-visibility: hidden

docs/deployment/ninja/command/info.adoc

@@ -0,0 +1,3 @@
+= Info
+
+#TODO#

docs/deployment/ninja/command/initial-objects.adoc

@@ -0,0 +1,3 @@
+= Initial objects
+
+#TODO#

docs/deployment/ninja/command/keys.adoc

@@ -0,0 +1,10 @@
+= Keys
+
+Command that lists keys from keystore defined in `${midpoint.home}/config.xml` using `keystore/keyStorePath`.
+Password for keys can be filled in using `-k <PASSWORD>` or `-K` to ask for password interactively.
+
+.List keys in with aliases from keystore located in `${midpoint.home}`
+[source,bash]
+----
+./bin/ninja.sh keys -K
+----

docs/deployment/ninja/command/pre-upgrade-check.adoc

@@ -0,0 +1,25 @@
+= Pre-upgrade check
+
+Pre-upgrade check is a simple check that verifies that current midPoint version matches version of distribution that is going to be upgraded.
+There are two items being checked:
+
+* database schema version
+* midPoint cluster nodes version
+
+== Database schema version check
+
+This check verifies that database schema version matches supported version.
+Database schema version is stored in `m_global_metadata` table and separate version is stored for midPoint repository and audit.
+Schema version check can be skipped if necessary using option `--skip-database-version-check`.
+
+== Nodes version check
+
+This check verifies that all nodes in midPoint cluster have the same version and that version is eligible for upgrade.
+Nodes version check can be skipped if necessary using option `--skip-nodes-version-check`.
+
+.Example of how to do pre-upgrade check
+[source,bash]
+----
+./bin/ninja.sh pre-upgrade-check \
+  --skip-nodes-version-check
+----

docs/deployment/ninja/command/run-sql.adoc

@@ -0,0 +1,3 @@
+= Run SQL
+
+#TODO#

docs/deployment/ninja/command/trace.adoc

@@ -0,0 +1,3 @@
+= Trace
+
+#TODO#

docs/deployment/ninja/command/upgrade-distribution.adoc

@@ -0,0 +1,3 @@
+= Upgrade distribution
+
+#TODO#

docs/deployment/ninja/command/upgrade-installation.adoc

@@ -0,0 +1,3 @@
+= Upgrade installation
+
+#TODO#

docs/deployment/ninja/command/upgrade-objects.adoc

@@ -0,0 +1,3 @@
+= Upgrade objects
+
+#TODO#

docs/deployment/ninja/command/verify.adoc

@@ -0,0 +1,22 @@
+= Verify
+
+Command that verifies objects in midPoint repository.
+It displays warnings about objects to `SYSOUT` or file.
+Similarly to export, one can define oid, multiple types or filter to filter verified objects.
+Simple usage to verify all objects in the repository for all warnings:
+
+.Example which verifies all objects in repository, checks all warnings
+[source,bash]
+----
+./bin/ninja.sh verify
+----
+
+There is a `-w` switch that can be used to select specific warnings to display.
+Currently, it only supports values deprecated and plannedRemoval.
+Following command will show warnings about planned removal of items used by all objects in the repository:
+
+.Example which verifies all objects in repository, checks only planned removal of items
+[source,bash]
+----
+./bin/ninja.sh verify --verification-category planned_removal
+----