| // |
| // Licensed 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. |
| // |
| |
| === Artifacts repositories and URLs |
| |
| 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> |
| ---- |
| |
| Doing this will make sure the above bundle is installed while installing the feature. |
| |
| However, Karaf provides several URL handlers, in addition to the usual ones (file, http, etc...). One of these is the Maven URL handler, which allow reusing maven repositories to point to the bundles. |
| |
| You can deploy bundles from file system without using Maven |
| |
| As we can use file: as protocol handler to deploy bundles, you can use the following syntax to deploy bundles when they are |
| located in a directory which is not available using Maven |
| |
| ---- |
| <bundle>file:base/bundles/org.apache.servicemix.nmr.api-1.0.0-m2.jar</bundle> |
| ---- |
| |
| Note: The path is relative to the Apache Karaf installation directory |
| |
| ==== Maven URL Handler |
| |
| The equivalent of the above bundle would be: |
| |
| ---- |
| <bundle>mvn:org.apache.servicemix.nmr/org.apache.servicemix.nmr.api/1.0.0-m2</bundle> |
| ---- |
| |
| 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.mvn.cfg`. |
| Full reference of `org.ops4j.pax.url.mvn` PID configuration can be found on https://ops4j1.jira.com/wiki/display/paxurl/Aether+Configuration[the pax-web Wiki page]. |
| |
| The most important property is: |
| |
| * `org.ops4j.pax.url.mvn.repositories` : Comma separated list of remote repository URLs that are checked in order of occurence when resolving maven artifacts |
| |
| Two other significant properties are: |
| |
| * `org.ops4j.pax.url.mvn.defaultRepositories` : 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 the 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 the user's life easier and to provide more _domain_ oriented approach, Karaf provides several shell commands that makes Maven configuration easier. |
| |
| ===== maven:summary |
| |
| This command shows a quick summary about current `org.ops4j.pax.url.mvn` PID configuration. For example: |
| |
| [source,options="nowrap"] |
| ---- |
| 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 |
| ---- |
| |
| * `-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 a much more readable way than the 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 a given repository |
| * `-x` shows credentials for a given repository (if defined) |
| |
| ===== maven:password |
| |
| `org.ops4j.pax.url.mvn` bundle uses the Aether library to handle Maven resolution. It uses the `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 the `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 the 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 the encrypted _master password_. We can however make this password persistent. This will |
| result in the creation of a new `settings-security.xml` file and a change in the `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 the 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 the `maven:repository-add` command. |
| |
| Here's how a 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 a 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, a new `settings.xml` file was created. The reason is that although a 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 the 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 a summary of options for the `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> |
| ---- |
