[KARAF-5008] Add documentation section about maven:* commands
Project: http://git-wip-us.apache.org/repos/asf/karaf/repo Commit: http://git-wip-us.apache.org/repos/asf/karaf/commit/2aeb865f Tree: http://git-wip-us.apache.org/repos/asf/karaf/tree/2aeb865f Diff: http://git-wip-us.apache.org/repos/asf/karaf/diff/2aeb865f Branch: refs/heads/master Commit: 2aeb865f6ca8b557a851468ef2ffd9fac790dac4 Parents: 995a482 Author: Grzegorz Grzybek <[email protected]> Authored: Thu Jun 22 13:14:13 2017 +0200 Committer: Grzegorz Grzybek <[email protected]> Committed: Thu Jun 22 13:14:13 2017 +0200 ---------------------------------------------------------------------- manual/pom.xml | 5 + manual/src/main/asciidoc/user-guide/urls.adoc | 295 ++++++++++++++++++++- 2 files changed, 294 insertions(+), 6 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/karaf/blob/2aeb865f/manual/pom.xml ---------------------------------------------------------------------- diff --git a/manual/pom.xml b/manual/pom.xml index 109dd9f..d0f5b4d 100644 --- a/manual/pom.xml +++ b/manual/pom.xml @@ -177,6 +177,11 @@ <artifactId>org.apache.karaf.subsystem.core</artifactId> <version>${project.version}</version> </dependency> + <dependency> + <groupId>org.apache.karaf.maven</groupId> + <artifactId>org.apache.karaf.maven.core</artifactId> + <version>${project.version}</version> + </dependency> <!-- Additional Required Dependencies --> <dependency> <groupId>org.apache.felix</groupId> http://git-wip-us.apache.org/repos/asf/karaf/blob/2aeb865f/manual/src/main/asciidoc/user-guide/urls.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/user-guide/urls.adoc b/manual/src/main/asciidoc/user-guide/urls.adoc index 15f6911..f149f75 100644 --- a/manual/src/main/asciidoc/user-guide/urls.adoc +++ b/manual/src/main/asciidoc/user-guide/urls.adoc @@ -16,6 +16,7 @@ The main information provided by a feature is the set of OSGi bundles that defines the application. Such bundles are URLs pointing to the actual bundle jars. For example, one would write the following definition: +[source,options="nowrap"] ---- <bundle>http://repo1.maven.org/maven2/org/apache/servicemix/nmr/org.apache.servicemix.nmr.api/1.0.0-m2/org.apache.servicemix.nmr.api-1.0.0-m2.jar</bundle> ---- @@ -45,16 +46,298 @@ The equivalent of the above bundle would be: In addition to being less verbose, the Maven url handlers can also resolve snapshots and can use a local copy of the jar if one is available in your Maven local repository. -The `org.ops4j.pax.url.mvn` bundle resolves `mvn` URLs. It can be configured using the file `etc/org.ops4j.pax.url.cfg` +The `org.ops4j.pax.url.mvn` bundle resolves `mvn` URLs. It can be configured using the file `etc/org.ops4j.pax.url.cfg`. +Full reference of `org.ops4j.pax.url.mvn` PID configuration can be found https://ops4j1.jira.com/wiki/display/paxurl/Aether+Configuration[on pax-web Wiki page]. -The most important property is : +The most important property is: -* `org.ops4j.pax.url.mvn.repositories` : Comma separated list of repository remote repository URLs that are checked in order of occurence when resolving maven artifacts +* `org.ops4j.pax.url.mvn.repositories` : Comma separated list of remote repository URLs that are checked in order of occurence when resolving maven artifacts -By default, snapshots are disabled. To enable an URL for snapshots append @snapshots to a repository entry. For example +Two other significant properties are: +* `org.ops4j.pax.url.mvn.defaulRepositories` : Comma separated list of locations that are checked before querying remote repositories. These can be treated as read-only repositories, as nothing is written there during artifact resolution. +* `org.ops4j.pax.url.mvn.localRepository` : by default (implicitly) it's standard `~/.m2/repository` location. This + local repository is used to store artifacts downloaded from one of remote repositories, so at next resolution attempt + no remote request is issued. + +By default, snapshots are disabled. To enable an URL for snapshots append `@snapshots` to a repository URI. For example + +---- +org.ops4j.pax.url.mvn.repositories = http://www.example.org/repo@snapshots +---- + +Repositories on the local machine are supported through `file:/` URLs. + +==== Maven configuration commands + +Full configuration of `org.ops4j.pax.url.mvn` bundle can be done using `org.ops4j.pax.url.mvn` PID (see `etc/org.ops4j.pax.url.mvn.cfg` file). This however may be cumbersome in some scenarios. + +In order to make user's life easier and provide more _domain_ oriented approach, Karaf provides several shell commands that makes Maven configuration easier. + +===== maven:summary + +This command shows quick summary about current `org.ops4j.pax.url.mvn` PID configuration. For example: + +[source,options="nowrap"] ---- -http://www.example.org/repo@snapshots +karaf@root()> maven:summary -s + +Option â Value â Source +âââââââââââââââââââââââââââ¼âââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââ¼âââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââ +Local repository â /home/ggrzybek/.m2/repository â Implicit ${user.home}/.m2/repository +Settings file â /home/ggrzybek/.m2/settings.xml â Implicit ${user.home}/.m2/settings.xml +Security settings file â /home/ggrzybek/.m2/settings-security.xml â Implicit ${user.home}/.m2/settings-security.xml +Global update policy â â Implicit "never", but doesn't override repository-specific value +Global checksum policy â warn â Default "warn" +Update releases â false â Default "false" +Require Config Admin â true â BundleContext property (org.ops4j.pax.url.mvn.requireConfigAdminConfig) +Use fallback repository â false â Explicit org.ops4j.pax.url.mvn PID configuration (org.ops4j.pax.url.mvn.useFallbackRepositories) +Offline mode â false â Default "false" +SSL/TLS certificate check â true â Explicit org.ops4j.pax.url.mvn PID configuration (org.ops4j.pax.url.mvn.certificateCheck) +Remote repositories â http://repo1.maven.org/maven2/ â PID configuration + â http://repository.apache.org/content/groups/snapshots-group/ â PID configuration + â https://oss.sonatype.org/content/repositories/snapshots/ â PID configuration + â https://oss.sonatype.org/content/repositories/ops4j-snapshots/ â PID configuration +Default repositories â file:/data/servers/apache-karaf-4.2.0-SNAPSHOT/system/ â PID configuration + â file:/data/servers/apache-karaf-4.2.0-SNAPSHOT/data/kar/ â PID configuration +HTTP proxies â proxy.everfree.forest:3128 â Maven XML settings ---- -Repositories on the local machine are supported through `file:/` URLs. \ No newline at end of file +* `-s` option show where the value of the option come from. It may be implicit, explicit or default. We can also see + whether the value was configured in PID or in `settings.xml` file. +* `-p` option uses original option names from `org.ops4j.pax.url.mvn` PID instead of descriptive option names +* `-d` option shows additional description, explaining what given option should be used for +* `-x` option turns on password display - if there's master password configured, it'll be displayed in clear text. + This option may be used only by user with `admin` role. + + +===== maven:repository-list + +This command displays all configured Maven repositories - in much more readable way than plain `config:proplist --pid org.ops4j.pax.url.mvn` command does. + +[source,options="nowrap"] +---- +karaf@root()> maven:repository-list -v + +== Remote repositories +ID â URL â Releases â Snapshots â Defined in +âââââââââââââââââââââââââââââââââ¼âââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââ¼ââââââââââââââ¼ââââââââââââââ¼âââââââââââ +central â http://repo1.maven.org/maven2/ â yes (daily) â no â PID +apache â http://repository.apache.org/content/groups/snapshots-group/ â no â yes (daily) â PID +sonatype.snapshots.deploy â https://oss.sonatype.org/content/repositories/snapshots/ â no â yes (daily) â PID +ops4j.sonatype.snapshots.deploy â https://oss.sonatype.org/content/repositories/ops4j-snapshots/ â no â yes (daily) â PID +special â https://repository.everfree.forest/ â yes (daily) â no â SETTINGS + +== Default repositories +ID â URL â Releases â Snapshots +âââââââââââââââââââââââââ¼âââââââââââââââââââââââââââââââââââââââââââââââââââââââââââ¼ââââââââââââââ¼ââââââââââââ +system.repository â file:/data/servers/apache-karaf-4.2.0-SNAPSHOT/system/ â yes (daily) â yes (daily) +kar.repository â file:/data/servers/apache-karaf-4.2.0-SNAPSHOT/data/kar/ â yes (daily) â yes (daily) +child.system.repository â file:/data/servers/apache-karaf-4.2.0-SNAPSHOT/system/ â yes (daily) â yes (daily) +---- + +* `-v` option shows additional information about policies related to given repository +* `-x` shows credentials for given repository (if defined) + +===== maven:password + +`org.ops4j.pax.url.mvn` bundle uses Aether library to handle Maven resolution. It uses `settings.xml` file if +credentials have to be used when accessing remote Maven repositories. This isn't done by `org.ops4j.pax.url.mvn`, +but by Aether itself (or rather maven-settings library). When dealing with `settings.xml` file, passwords that +are stored there may need to be decrypted. +Outside of Karaf, we can use `mvn -emp` and `mvn -ep` passwords and manually configure `~/.m2/settings-security.xml` +file. + +Karaf makes the task of managing credentials easier. + +In order to use encrypted repository (or http proxy) passwords inside `settings.xml` file, Maven must know the _master +password_ stored inside `settings-security.xml` file. This file isn't usually present inside `~/.m2` directory and if +there's a need to use it, one has to be created manually. + +Here's the way to encrypt Maven _master password_ (which is used to encrypt ordinary passwords for repository or http proxies): + +[source,options="nowrap"] +---- +karaf@root()> maven:password -emp +Master password to encrypt: ***** +Encrypted master password: {y+p9TiYuwVEHMHV14ej0Ni34zBnXXQrIOqjww/3Ro6U=} +---- + +The above usage simply prints encrypted _master password_. We can however make this password persistent. This will +result in new `settings-security.xml` file to be created and change in `org.ops4j.pax.url.mvn.security` property. + +NOTE: Karaf maven commands will never overwrite your current `~/.m2/settings.xml` or `~/.m2/settings-security.xml` files. +If there's a need to change these files, maven commands will make a copy of existing file and set relevant `org.ops4j.pax.url.mvn` PID options +to point to new locations. + +[source,options="nowrap"] +---- +karaf@root()> maven:password -emp --persist +Maven security settings will be stored in new file. This file will be used in org.ops4j.pax.url.mvn.security property. Continue? (y/N) y +Master password to encrypt: ***** +Encrypted master password: {lPPIFSUcPrMHnhwdauttAJYZcOe1D9sYGj4rwoaTwnY=} +New security settings stored in "/data/servers/apache-karaf-4.2.0-SNAPSHOT/data/cache/bundle53/data/maven-security-settings-1498120766139.xml" +karaf@root()> maven:summary -x + +Option â Value +âââââââââââââââââââââââââââ¼âââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââ +... +Security settings file â /data/servers/apache-karaf-4.2.0-SNAPSHOT/data/cache/bundle53/data/maven-security-settings-1498120766139.xml +Master password â admin +... +---- + +Now, when Maven _master password_ is set, we can encrypt ordinary passwords that may be then used when defining/changing +remote repositories or http proxies: + +[source,options="nowrap"] +---- +karaf@root()> maven:password -ep +Password to encrypt: ***** +Encrypted password: {fHl8U3pINkEH7RR1CufRT+utj5gJHfqsRgd6wTo92Eo=} +You can use this encrypted password when defining repositories and proxies +---- + +===== Configuring repositories (default and remote) + +As mentioned before, there are two kinds of repositories that are used/queried by `org.ops4j.pax.url.mvn` bundle when resolving +`mvn:` based URIs: + +default repositories:: These are read-only local repositories that are simply queried before performing any remote access. + The best example of such repository is `$KARAF_HOME/system` directory. + +remote repositories:: These are well-known Maven remote repositories - usually accessible over http(s) protocol. Popular + repositories are Sonatype Nexus or JFrog Artifactory. + +Both kinds of repositories may be created using `maven:repository-add` command. + +Here's how default repository may be created: + +[source,options="nowrap"] +---- +karaf@root()> maven:repository-add --default -id my.default.repository --snapshots '${karaf.home}/special-repository' + +... +== Default repositories +ID â URL â Releases â Snapshots +âââââââââââââââââââââââââ¼âââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââ¼ââââââââââââââ¼ââââââââââââ +... +my.default.repository â file:/data/servers/apache-karaf-4.2.0-SNAPSHOT/special-repository/ â yes (daily) â yes (daily) +---- + +For remote repository, we can specify more options (like credentials or update policies): + +[source,options="nowrap"] +---- +karaf@root()> maven:repository-add -idx 0 -id my.remote.repository --snapshots -up never --username admin --password '{fHl8U3pINkEH7RR1CufRT+utj5gJHfqsRgd6wTo92Eo=}' http://localhost/cloud-repository +Maven settings will be updated and org.ops4j.pax.url.mvn.settings property will change. Continue? (y/N) y +New settings stored in "/data/servers/apache-karaf-4.2.0-SNAPSHOT/data/cache/bundle53/data/maven-settings-1498121385253.xml" + +karaf@root()> maven:repository-list -x + +== Remote repositories +ID â URL â Username â Password +âââââââââââââââââââââââââââââââââ¼âââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââ¼âââââââââââ¼âââââââââ +my.remote.repository â http://localhost/cloud-repository/ â admin â admin +... +---- + +In the above example, new `settings.xml` file was created. The reason is that although new repository itself was added +to `org.ops4j.pax.url.mvn.repositories` property, the credentials had to be stored in `settings.xml` file: + +[source,options="nowrap"] +---- +<servers> + <server> + <username>admin</username> + <password>{fHl8U3pINkEH7RR1CufRT+utj5gJHfqsRgd6wTo92Eo=}</password> + <id>my.remote.repository</id> + </server> +</servers> +---- + +Here's summary of all options for `maven:repository-add` command: + +* `-id` mandatory identifier of repository +* `-d` option may be used to configure default repositories instead of remote ones +* `-nr` option disables non-SNAPSHOT artifacts resolution in this repository +* `-s` option enables SNAPSHOT artifacts resolution in this repository +* `-up` sets _update policy_ for given repository (`daily`, `always`, `never`, `interval:MINUTES`) +* `-cp` sets _checksum policy_ for given repository (`fail`, `warn`, `ignore`) +* `-f` disables confirmation prompts for commands +* `-idx` allows to insert a repository at given position (instead of simply appending new repository at the end of current list of repositories) +* `-u` sets username for remote repository access +* `-p` sets password for remote repository access (may be encrypted using `maven:password -ep`) + +After creating a repository, it may be deleted (using `maven:repository-remove` command) or changed (`maven:repository-change` command). +All the options are the same as in `maven:repository-add` command. When removing a repository, only `-id` (and possibly `-d`) options are needed. + +[source,options="nowrap"] +---- +karaf@root()> repository-remove -d -id my.default.repository +Are you sure to remove repository with ID "my.default.repository" for URL file:/data/servers/apache-karaf-4.2.0-SNAPSHOT/special-repository/? (y/N) y + +karaf@root()> repository-change -id special --username discord --password d1sc0rd +Maven settings will be updated and org.ops4j.pax.url.mvn.settings property will change. Continue? (y/N) y +New settings stored in "/data/servers/apache-karaf-4.2.0-SNAPSHOT/data/cache/bundle53/data/maven-settings-1498122026388.xml" +---- + +===== Configuring HTTP proxies + +When accessing remote repositories using `org.ops4j.pax.url.mvn` (Aether library) there may be a need to let Maven/Aether +know about HTTP proxies to use. HTTP proxies *can't be configured* inside `etc/org.ops4j.pax.url.mvn.cfg` file. It has to +be done in `settings.xml` and its location has to be set in `org.ops4j.pax.url.mvn.settings` PID property. + +`maven:http-proxy` command can be used to add/change/remove HTTP proxy definition. It automatically does a copy +of existing `settings.xml` file and changes `org.ops4j.pax.url.mvn.settings` PID property. + +For example: + +[source,options="nowrap"] +---- +karaf@root()> maven:http-proxy-list -x + +ID â Host â Port â Non-proxy hosts â Username â Password +ââââââââââ¼ââââââââââââââââââââââââ¼âââââââ¼ââââââââââââââââââ¼âââââââââââ¼âââââââââââââ +my.proxy â proxy.everfree.forest â 3128 â 192.168.2.* â admin â super-secret + +karaf@root()> maven:http-proxy --remove -id my.proxy +New settings stored in "/data/servers/apache-karaf-4.2.0-SNAPSHOT/data/cache/bundle53/data/maven-settings-1498122255098.xml" + +No HTTP proxies configured in /data/servers/apache-karaf-4.2.0-SNAPSHOT/data/cache/bundle53/data/maven-settings-1498122255098.xml + +karaf@root()> maven:http-proxy --add -id my.proxy --username discord --password '{fHl8U3pINkEH7RR1CufRT+utj5gJHfqsRgd6wTo92Eo=}' --non-proxy-hosts '127.*|192.168.*|localhost' proxy.everfree.forest:3128 +New settings stored in "/data/servers/apache-karaf-4.2.0-SNAPSHOT/data/cache/bundle53/data/maven-settings-1498122328731.xml" + +karaf@root()> maven:http-proxy-list -x + +ID â Host â Port â Non-proxy hosts â Username â Password +ââââââââââ¼ââââââââââââââââââââââââ¼âââââââ¼ââââââââââââââââââââââââââââ¼âââââââââââ¼âââââââââ +my.proxy â proxy.everfree.forest â 3128 â 127.*|192.168.*|localhost â discord â admin +---- + +Here's summary of options for `maven:http-proxy` command: + +* `-id` identifier of HTTP proxy +* `-add` / `--change` / `--remove` is an operation to perform on proxy +* `-f` disables confirmation prompts for commands +* `-u` sets username for remote HTTP proxy +* `-p` sets password for remote HTTP proxy (may be encrypted using `maven:password -ep`) +* `-n` sets _non proxy hosts_ option, which is `|`-separated list of glob patterns for IP addresses/host names that should be + accessed bypassing HTTP proxy + +`maven:http-proxy` configures for example this section in `settings.xml`: + +[source,options="nowrap"] +---- +<proxies> + <proxy> + <username>discord</username> + <password>{fHl8U3pINkEH7RR1CufRT+utj5gJHfqsRgd6wTo92Eo=}</password> + <port>3128</port> + <host>proxy.everfree.forest</host> + <nonProxyHosts>127.*|192.168.*|localhost</nonProxyHosts> + <id>my.proxy</id> + </proxy> +</proxies> +----
