Modified: maven/website/content/guides/mini/guide-encryption.html ============================================================================== --- maven/website/content/guides/mini/guide-encryption.html (original) +++ maven/website/content/guides/mini/guide-encryption.html Thu Feb 9 00:34:05 2023 @@ -2,7 +2,7 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/mini/guide-encryption.apt at 2023-02-08 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/markdown/guides/mini/guide-encryption.md at 2023-02-09 | Rendered using Apache Maven Fluido Skin 1.11.1 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang=""> @@ -10,8 +10,7 @@ <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M4" /> - <meta name="author" content="Oleg Gusakov -Robert Scholte" /> + <meta name="author" content="Oleg Gusakov, Robert Scholte" /> <meta name="date" content="2014-03-23" /> <title>Maven – Password Encryption</title> <link rel="stylesheet" href="../../css/apache-maven-fluido-1.11.1.min.css" /> @@ -49,8 +48,8 @@ Robert Scholte" /> <ul class="breadcrumb"> <li class=""><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li class=""><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - <li class="active ">Password Encryption <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/mini/guide-encryption.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> - <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2023-02-08</li> + <li class="active ">Password Encryption <a href="https://github.com/apache/maven-site/tree/master/content/markdown/guides/mini/guide-encryption.md";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2023-02-09</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> <li class="pull-right"><a href="../../download.cgi" title="Download">Download</a></li> @@ -153,55 +152,90 @@ Robert Scholte" /> </div> </header> <main id="bodyColumn" class="span10" > -<section> -<h1><a id="Password_Encryption">Password Encryption</a></h1> -<ol style="list-style-type: decimal"> -<li><a href="#Introduction">Introduction</a></li> -<li><a href="#How_to_create_a_master_password">How to create a master password</a></li> -<li><a href="#How_to_encrypt_server_passwords">How to encrypt server passwords</a></li> -<li><a href="#How_to_keep_the_master_password_on_removable_drive">How to keep the master password on removable drive</a></li> -<li><a href="#Tips">Tips</a></li></ol><section> -<h2><a id="Introduction">Introduction</a></h2> +<!-- +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. +--> +<section><section> +<h2>Password Encryption</h2> +<p>1 <a href="Introduction">Introduction</a></p> +<p>1 <a href="How_to_create_a_master_password">How to create a master password</a></p> +<p>1 <a href="How_to_encrypt_server_passwords">How to encrypt server passwords</a></p> +<p>1 <a href="How_to_keep_the_master_password_on_removable_drive">How to keep the master password on removable drive</a></p> +<p>1 <a href="Tips">Tips</a></p><section> +<h3>Introduction</h3> <p>Maven supports server password encryption. The main use case, addressed by this solution is:</p> <ul> -<li>multiple users share the same build machine (server, CI box)</li> -<li>some users have the privilege to deploy Maven artifacts to repositories, some don't. -<ul> -<li>this applies to any server operations, requiring authorization, not only deployment</li></ul></li> -<li><code>settings.xml</code> is shared between users</li></ul> + +<li> +<p>multiple users share the same build machine (server, CI box)</p></li> +<li> +<p>some users have the privilege to deploy Maven artifacts to repositories, some don't.</p></li> +<li> +<p>this applies to any server operations, requiring authorization, not only deployment</p></li> +<li> +<p><code>settings.xml</code> is shared between users</p></li> +</ul> <p>The implemented solution adds the following capabilities:</p> <ul> -<li>authorized users have an additional <code>settings-security.xml</code> file in their <code>${user.home}/.m2</code> folder -<ul> -<li>this file either contains encrypted <b>master password</b>, used to encrypt other passwords</li> -<li>or it can contain a <b>relocation</b> - reference to another file, possibly on removable storage</li> -<li>this password is created first via CLI for now</li></ul></li> -<li>server entries in the <code>settings.xml</code> have passwords and/or keystore passphrases encrypted -<ul> -<li>for now - this is done via CLI <b>after</b> master password has been created and stored in appropriate location</li></ul></li></ul></section><section> -<h2><a id="How_to_create_a_master_password">How to create a master password</a></h2> + +<li> +<p>authorized users have an additional <code>settings-security.xml</code> file in their <code>$\{user.home\}/.m2</code> folder</p></li> +<li> +<p>this file either contains encrypted <strong>master password</strong>, used to encrypt other passwords</p></li> +<li> +<p>or it can contain a <strong>relocation</strong> - reference to another file, possibly on removable storage</p></li> +<li> +<p>this password is created first via CLI for now</p></li> +<li> +<p>server entries in the <code>settings.xml</code> have passwords and/or keystore passphrases encrypted</p></li> +<li> +<p>for now - this is done via CLI <strong>after</strong> master password has been created and stored in appropriate location</p></li> +</ul></section><section> +<h3>How to create a master password</h3> <p>Use the following command line:</p> -<div> -<pre>mvn --encrypt-master-password <password></pre></div> -<p><i>Note:</i> Since Maven 3.2.1 the password argument should no longer be used (see <a href="#Tips">Tips</a> below for more information). Maven will prompt for the password. Earlier versions of Maven will not prompt for a password, so it must be typed on the command-line in plaintext.</p> + +<div class="source"><pre class="prettyprint linenums"><code>mvn --encrypt-master-password <password> +</code></pre></div> +<p><em>Note:</em> Since Maven 3.2.1 the password argument should no longer be used (see <a href="Tips">Tips</a> below for more information). Maven will prompt for the password. Earlier versions of Maven will not prompt for a password, so it must be typed on the command-line in plaintext.</p> <p>This command will produce an encrypted version of the password, something like</p> -<div> -<pre>{jSMOWnoPFgsHVpMvz5VrIt5kRbzGpI8u+9EF1iFQyJQ=}</pre></div> -<p>Store this password in the <code>${user.home}/.m2/settings-security.xml</code>; it should look like</p> -<div class="source"><pre class="prettyprint linenums"><settingsSecurity> + +<div class="source"><pre class="prettyprint linenums"><code>{jSMOWnoPFgsHVpMvz5VrIt5kRbzGpI8u+9EF1iFQyJQ=} +</code></pre></div> +<p>Store this password in the <code>$\{user.home\}/.m2/settings-security.xml</code>; it should look like</p> + +<div class="source"><pre class="prettyprint linenums"><code><settingsSecurity> <master>{jSMOWnoPFgsHVpMvz5VrIt5kRbzGpI8u+9EF1iFQyJQ=}</master> -</settingsSecurity></pre></div> +</settingsSecurity> +</code></pre></div> <p>When this is done, you can start encrypting existing server passwords.</p></section><section> -<h2><a id="How_to_encrypt_server_passwords">How to encrypt server passwords</a></h2> +<h3>How to encrypt server passwords</h3> <p>You have to use the following command line:</p> -<div> -<pre>mvn --encrypt-password <password></pre></div> -<p><i>Note:</i>Just like <code>--encrypt-master-password</code> the password argument should no longer be used since Maven 3.2.1 (see <a href="#Tips">Tips below for more information.</a>).</p> + +<div class="source"><pre class="prettyprint linenums"><code>mvn --encrypt-password <password> +</code></pre></div> +<p>_Note:_Just like <code>--encrypt-master-password</code> the password argument should no longer be used since Maven 3.2.1 (see <a href="Tips">Tips below for more information.</a>).</p> <p>This command produces an encrypted version of it, something like</p> -<div> -<pre>{COQLCE6DU6GtcS5P=}</pre></div> + +<div class="source"><pre class="prettyprint linenums"><code>{COQLCE6DU6GtcS5P=} +</code></pre></div> <p>Copy and paste it into the servers section of your <code>settings.xml</code> file. This will look like:</p> -<div class="source"><pre class="prettyprint linenums"><settings> + +<div class="source"><pre class="prettyprint linenums"><code><settings> ... <servers> ... @@ -213,9 +247,11 @@ Robert Scholte" /> ... </servers> ... -</settings></pre></div> +</settings> +</code></pre></div> <p>Please note that password can contain any information outside of the curly brackets, so that the following will still work:</p> -<div class="source"><pre class="prettyprint linenums"><settings> + +<div class="source"><pre class="prettyprint linenums"><code><settings> ... <servers> ... @@ -227,51 +263,65 @@ Robert Scholte" /> ... </servers> ... -</settings></pre></div> +</settings> +</code></pre></div> <p>Then you can use, say, deploy plugin, to write to this server:</p> -<div> -<pre>mvn deploy:deploy-file -Durl=https://maven.corp.com/repo \ + +<div class="source"><pre class="prettyprint linenums"><code>mvn deploy:deploy-file -Durl=https://maven.corp.com/repo \ -DrepositoryId=my.server \ - -Dfile=your-artifact-1.0.jar \</pre></div></section><section> -<h2><a id="How_to_keep_the_master_password_on_removable_drive">How to keep the master password on removable drive</a></h2> + -Dfile=your-artifact-1.0.jar \ +</code></pre></div></section><section> +<h3>How to keep the master password on removable drive</h3> <p>Create the master password exactly as described above, and store it on a removable drive, for instance on OSX, my USB drive mounts as <code>/Volumes/mySecureUsb</code>, so I store</p> -<div class="source"><pre class="prettyprint linenums"><settingsSecurity> + +<div class="source"><pre class="prettyprint linenums"><code><settingsSecurity> <master>{jSMOWnoPFgsHVpMvz5VrIt5kRbzGpI8u+9EF1iFQyJQ=}</master> -</settingsSecurity></pre></div> +</settingsSecurity> +</code></pre></div> <p>in the file <code>/Volumes/mySecureUsb/secure/settings-security.xml</code></p> -<p>And then I create <code>${user.home}/.m2/settings-security.xml</code> with the following content:</p> -<div class="source"><pre class="prettyprint linenums"><settingsSecurity> +<p>And then I create <code>$\{user.home\}/.m2/settings-security.xml</code> with the following content:</p> + +<div class="source"><pre class="prettyprint linenums"><code><settingsSecurity> <relocation>/Volumes/mySecureUsb/secure/settings-security.xml</relocation> -</settingsSecurity></pre></div> +</settingsSecurity> +</code></pre></div> <p>This assures that encryption only works when the USB drive is mounted by the OS. This addresses a use case where only certain people are authorized to deploy and are issued these devices.</p></section><section> -<h2><a id="Tips">Tips</a></h2><section> -<h3>Escaping curly-brace literals in your password <i>(Since: Maven 2.2.0)</i></h3> -<p>At times, you might find that your password (or the encrypted form of it) contains '{' or '}' as a literal value. If you added such a password as-is to your settings.xml file, you would find that Maven does strange things with it. Specifically, Maven treats all the characters preceding the '{' literal, and all the characters after the '}' literal, as comments. Obviously, this is not the behavior you want. What you really need is a way of <b>escaping</b> the curly-brace literals in your password.</p> -<p>You can do this with the widely used '\' escape character. If your password looks like this:</p> -<div> -<pre>jSMOWnoPFgsHVpMvz5VrIt5kRbzGpI8u+{EF1iFQyJQ=</pre></div> +<h3>Tips</h3><section> +<h4>Escaping curly-brace literals in your password <em>(Since: Maven 2.2.0)</em></h4> +<p>At times, you might find that your password (or the encrypted form of it) contains ‘{’ or ‘}’ as a literal value. If you added such a password as-is to your settings.xml file, you would find that Maven does strange things with it. Specifically, Maven treats all the characters preceding the ‘{’ literal, and all the characters after the ‘}’ literal, as comments. Obviously, this is not the behavior you want. What you really need is a way of <strong>escaping</strong> the curly-brace literals in your password.</p> +<p>You can do this with the widely used ‘\’ escape character. If your password looks like this:</p> + +<div class="source"><pre class="prettyprint linenums"><code>jSMOWnoPFgsHVpMvz5VrIt5kRbzGpI8u+{EF1iFQyJQ= +</code></pre></div> <p>Then, the value you would add to your settings.xml looks like this:</p> -<div> -<pre>{jSMOWnoPFgsHVpMvz5VrIt5kRbzGpI8u+\{EF1iFQyJQ=}</pre></div></section><section> -<h3>Password Security</h3> + +<div class="source"><pre class="prettyprint linenums"><code>{jSMOWnoPFgsHVpMvz5VrIt5kRbzGpI8u+\{EF1iFQyJQ=} +</code></pre></div></section><section> +<h4>Password Security</h4> <p>Editing <code>settings.xml</code> and running the above commands can still leave your password stored locally in plaintext. You may want to check the following locations:</p> <ul> -<li>Shell history (e.g. by running <code>history</code>). You may want to clear your history after encrypting the above passwords</li> -<li>Editor caches (e.g. <code>~/.viminfo</code>)</li></ul> + +<li> +<p>Shell history (e.g. by running <code>history</code>). You may want to clear your history after encrypting the above passwords</p></li> +<li> +<p>Editor caches (e.g. <code>\~/.viminfo</code>)</p></li> +</ul> <p>Also note that the encrypted passwords can be decrypted by someone that has the master password and settings security file. Keep this file secure (or stored separately) if you expect the possibility that the <code>settings.xml</code> file may be retrieved.</p></section><section> -<h3>Password Escaping on different platforms</h3> +<h4>Password Escaping on different platforms</h4> <p>On some platforms it might be necessary to quote the password if it contains special characters like <code>%</code>, <code>!</code>, <code>$</code>, etc. For example on Windows you have to be careful about things like the following:</p> <p>The following example will not work on Windows:</p> -<div> -<pre>mvn --encrypt-master-password a!$%^b</pre></div> + +<div class="source"><pre class="prettyprint linenums"><code>mvn --encrypt-master-password a!$%^b +</code></pre></div> <p>whereas the following will work on Windows:</p> -<div> -<pre>mvn --encrypt-master-password "a!$%^b"</pre></div> + +<div class="source"><pre class="prettyprint linenums"><code>mvn --encrypt-master-password "a!$%^b" +</code></pre></div> <p>If you are on a linux/unix platform you should use single quotes for the above master password. Otherwise the master password will not work (caused by the dollar sign and the exclamation mark).</p></section><section> -<h3>Prompting for Password</h3> +<h4>Prompting for Password</h4> <p>In Maven before version 3.2.1 you have to give the password on the command line as an argument which means you might need to escape your password. In addition usually the shell stores the full history of commands you have entered, therefore anyone with access to your computer could restore the password from the shell`s history.</p> <p>Starting with Maven 3.2.1, the password is an optional argument. If you omit the password, you will be prompted for it which prevents all the issues mentioned above.</p> -<p>We strongly recommend using Maven 3.2.1 and above to prevent problems with escaping special characters and of course security issues related to bash history or environment issues in relationship with the password.</p></section></section></section> +<p>We strongly recommend using Maven 3.2.1 and above to prevent problems with escaping special characters and of course security issues related to bash history or environment issues in relationship with the password.</p></section></section></section></section> </main> </div> </div>
Modified: maven/website/content/guides/mini/guide-generating-sources.html ============================================================================== --- maven/website/content/guides/mini/guide-generating-sources.html (original) +++ maven/website/content/guides/mini/guide-generating-sources.html Thu Feb 9 00:34:05 2023 @@ -2,7 +2,7 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/mini/guide-generating-sources.apt at 2023-02-08 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/markdown/guides/mini/guide-generating-sources.md at 2023-02-09 | Rendered using Apache Maven Fluido Skin 1.11.1 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang=""> @@ -10,10 +10,8 @@ <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M4" /> - <meta name="author" content="Jason van Zyl -Karl Heinz Marbaise" /> - <meta name="date" content="2005-10-12 -2016-06-11" /> + <meta name="author" content="Jason van Zyl, Karl Heinz Marbaise" /> + <meta name="date" content="2005-10-12, 2016-06-11" /> <title>Maven – Guide to generating Sources</title> <link rel="stylesheet" href="../../css/apache-maven-fluido-1.11.1.min.css" /> <link rel="stylesheet" href="../../css/site.css" /> @@ -50,8 +48,8 @@ Karl Heinz Marbaise" /> <ul class="breadcrumb"> <li class=""><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li class=""><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - <li class="active ">Guide to generating Sources <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/mini/guide-generating-sources.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> - <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2023-02-08</li> + <li class="active ">Guide to generating Sources <a href="https://github.com/apache/maven-site/tree/master/content/markdown/guides/mini/guide-generating-sources.md";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2023-02-09</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> <li class="pull-right"><a href="../../download.cgi" title="Download">Download</a></li> @@ -156,11 +154,30 @@ Karl Heinz Marbaise" /> </div> </header> <main id="bodyColumn" class="span10" > -<section> -<h1>Guide to generating sources</h1> -<p>Let's run though a short example to try and help. To generate sources you must first have a plugin that participates in the <code>generate-sources</code> phase like the <a class="externalLink" href="http://www.antlr.org/api/maven-plugin/latest/";>ANTLR4 Maven Plugin</a>.</p> +<!-- +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. +--> +<section><section> +<h2>Guide to generating sources</h2> +<p>Let's run though a short example to try and help. To generate sources you must first have a plugin that participates in the <code>generate-sources</code> phase like the <a href="http://www.antlr.org/api/maven-plugin/latest/"; class="externalLink">ANTLR4 Maven Plugin</a>.</p> <p>So this is all fine and dandy, we have a plugin that wants to generate some sources from a Antlr4 grammar but how do we use it. You need to specify that you want to use it in your POM:</p> -<div class="source"><pre class="prettyprint linenums"> + +<div class="source"><pre class="prettyprint linenums"><code> <project> ... <build> @@ -182,8 +199,9 @@ Karl Heinz Marbaise" /> </build> ... </project> -</pre></div> -<p>If you then type <code>mvn compile</code> Maven will walk through the <a href="../introduction/introduction-to-the-lifecycle.html">lifecycle</a> and will eventually hit the <code>generate-sources</code> phase and see you have a plugin configured that wants to participate in that phase and the ANTLR4 Maven Plugin is executed with your given configuration. Furthermore during the compile you can observe that all the generated code (from your grammar files) will automatically being compiled without supplemental configuration.</p></section> + +</code></pre></div> +<p>If you then type <code>mvn compile</code> Maven will walk through the <a href="../introduction/introduction-to-the-lifecycle.html">lifecycle</a> and will eventually hit the <code>generate-sources</code> phase and see you have a plugin configured that wants to participate in that phase and the ANTLR4 Maven Plugin is executed with your given configuration. Furthermore during the compile you can observe that all the generated code (from your grammar files) will automatically being compiled without supplemental configuration.</p></section></section> </main> </div> </div> Modified: maven/website/content/guides/mini/guide-http-settings.html ============================================================================== --- maven/website/content/guides/mini/guide-http-settings.html (original) +++ maven/website/content/guides/mini/guide-http-settings.html Thu Feb 9 00:34:05 2023 @@ -2,7 +2,7 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/mini/guide-http-settings.apt at 2023-02-08 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/markdown/guides/mini/guide-http-settings.md at 2023-02-09 | Rendered using Apache Maven Fluido Skin 1.11.1 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang=""> @@ -48,8 +48,8 @@ <ul class="breadcrumb"> <li class=""><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li class=""><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - <li class="active ">Guide to Advanced HTTP Transport Configuration <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/mini/guide-http-settings.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> - <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2023-02-08</li> + <li class="active ">Guide to Advanced HTTP Transport Configuration <a href="https://github.com/apache/maven-site/tree/master/content/markdown/guides/mini/guide-http-settings.md";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2023-02-09</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> <li class="pull-right"><a href="../../download.cgi" title="Download">Download</a></li> @@ -152,40 +152,75 @@ </div> </header> <main id="bodyColumn" class="span10" > -<section> -<h1>Advanced Configuration of the Maven Resolver Transport</h1> -<ul> -<li><a href="#Advanced_Configuration_of_the_Maven_Resolver_Transport">Advanced Configuration of the Maven Resolver Transport</a> -<ul> -<li><a href="#Advanced_configuration_to_Transports">Advanced configuration to Transports</a> -<ul> -<li><a href="#HTTP_Headers">HTTP Headers</a></li> -<li><a href="#Connection_Timeouts">Connection Timeouts</a></li></ul></li> -<li><a href="#Advanced_Configuration_of_the_HttpClient_HTTP_Wagon">Advanced Configuration of the HttpClient HTTP Wagon</a> -<ul> -<li><a href="#Introduction">Introduction</a></li> -<li><a href="#The_Basics">The Basics</a></li> -<li><a href="#Configuring_GET.2C_HEAD.2C_PUT.2C_or_All_of_the_Above">Configuring GET, HEAD, PUT, or All of the Above</a></li> -<li><a href="#Taking_Control_of_Your_HTTP_Headers">Taking Control of Your HTTP Headers</a></li> -<li><a href="#Fine-Tuning_HttpClient_Parameters">Fine-Tuning HttpClient Parameters</a> -<ul> -<li><a href="#Non-String_Parameter_Values">Non-String Parameter Values</a></li> -<li><a href="#Example:_Using_Preemptive_Authentication">Example: Using Preemptive Authentication</a></li> -<li><a href="#Example:_Lifting_auth_scope_restriction_for_external_authentication_systems">Example: Lifting auth scope restriction for external authentication systems</a></li> -<li><a href="#Ignoring_Cookies">Ignoring Cookies</a></li></ul></li> -<li><a href="#Support_for_General-Wagon_Configuration_Standards">Support for General-Wagon Configuration Standards</a> +<!-- +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. +--> +<section><section> +<h2>Advanced Configuration of the Maven Resolver Transport</h2> <ul> -<li><a href="#HTTP_Headers_1">HTTP Headers</a></li> -<li><a href="#Connection_Timeouts_1">Connection Timeouts</a></li> -<li><a href="#Read_time_out">Read time out</a></li></ul></li> -<li><a href="#Resources">Resources</a></li></ul></li></ul></li></ul> -<p>You can use the default transport for a given protocol, or you can select the transport you want by using the configuration. For more information about existing Resolver transports see the <a class="externalLink" href="https://maven.apache.org/resolver/";> Resolver</a> site. The default transport in Maven 3.x is Transport-Wagon, the Wagon layer having been introduced in Maven 2.x. Since then, more modern transports were introduced as well, even supporting overlapping protocols. The default transport in Maven 4.x changed to the more modern <a class="externalLink" href="https://maven.apache.org/resolver/maven-resolver-transport-http/index.html";>"native" HTTP</a> transport.</p> -<p>Ultimate reference for resolver transport configuration can be found on <a class="externalLink" href="https://maven.apache.org/resolver/configuration.html";> this page</a>. While one can easily define simple typed values on command line using <code>-D...</code> switch, some more complex values, like HTTP headers, cannot.</p><section> -<h2>Advanced configuration to Transports</h2> + +<li> +<p><a href="Advanced_Configuration_of_the_Maven_Resolver_Transport">Advanced Configuration of the Maven Resolver Transport</a></p></li> +<li> +<p><a href="Advanced_configuration_to_Transports">Advanced configuration to Transports</a></p></li> +<li> +<p><a href="HTTP_Headers">HTTP Headers</a></p></li> +<li> +<p><a href="Connection_Timeouts">Connection Timeouts</a></p></li> +<li> +<p><a href="Advanced_Configuration_of_the_HttpClient_HTTP_Wagon">Advanced Configuration of the HttpClient HTTP Wagon</a></p></li> +<li> +<p><a href="Introduction">Introduction</a></p></li> +<li> +<p><a href="The_Basics">The Basics</a></p></li> +<li> +<p><a href="Configuring_GET.2C_HEAD.2C_PUT.2C_or_All_of_the_Above">Configuring GET, HEAD, PUT, or All of the Above</a></p></li> +<li> +<p><a href="Taking_Control_of_Your_HTTP_Headers">Taking Control of Your HTTP Headers</a></p></li> +<li> +<p><a href="Fine-Tuning_HttpClient_Parameters">Fine-Tuning HttpClient Parameters</a></p></li> +<li> +<p><a href="Non-String_Parameter_Values">Non-String Parameter Values</a></p></li> +<li> +<p><a href="Example:_Using_Preemptive_Authentication">Example: Using Preemptive Authentication</a></p></li> +<li> +<p><a href="Example:_Lifting_auth_scope_restriction_for_external_authentication_systems">Example: Lifting auth scope restriction for external authentication systems</a></p></li> +<li> +<p><a href="Ignoring_Cookies">Ignoring Cookies</a></p></li> +<li> +<p><a href="Support_for_General-Wagon_Configuration_Standards">Support for General-Wagon Configuration Standards</a></p></li> +<li> +<p><a href="HTTP_Headers_1">HTTP Headers</a></p></li> +<li> +<p><a href="Connection_Timeouts_1">Connection Timeouts</a></p></li> +<li> +<p><a href="Read_time_out">Read time out</a></p></li> +<li> +<p><a href="Resources">Resources</a></p></li> +</ul> +<p>You can use the default transport for a given protocol, or you can select the transport you want by using the configuration. For more information about existing Resolver transports see the <a href="https://maven.apache.org/resolver/"; class="externalLink">Resolver</a> site. The default transport in Maven 3.x is Transport-Wagon, the Wagon layer having been introduced in Maven 2.x. Since then, more modern transports were introduced as well, even supporting overlapping protocols. The default transport in Maven 4.x changed to the more modern <a href="https://maven.apache.org/resolver/maven-resolver-transport-http/index.html"; class="externalLink">“native” HTTP</a> transport.</p> +<p>Ultimate reference for resolver transport configuration can be found on <a href="https://maven.apache.org/resolver/configuration.html"; class="externalLink">this page</a>. While one can easily define simple typed values on command line using <code>-D...</code> switch, some more complex values, like HTTP headers, cannot.</p><section> +<h3>Advanced configuration to Transports</h3> <p>Using your <code>settings.xml</code> you can customize the transport configurations in several ways.</p><section> -<h3>HTTP Headers</h3> +<h4>HTTP Headers</h4> <p>In all HTTP transports, you can add your custom HTTP headers like this:</p> -<div class="source"><pre class="prettyprint linenums"><settings> + +<div class="source"><pre class="prettyprint linenums"><code><settings> <servers> <server> <id>my-server</id> @@ -199,11 +234,13 @@ </configuration> </server> </servers> -</settings></pre></div> +</settings> +</code></pre></div> <p>It is important to understand that the above approach does not allow you to turn off all of the default HTTP headers; nor does it allow you to specify headers on a per-method basis. However, this configuration remains available in all transports that support headers, like HTTP transports are.</p></section><section> -<h3>Connection Timeouts</h3> +<h4>Connection Timeouts</h4> <p>All transport implementations that perform some network access allow the configuration of a several timeouts, for example to allow the user to tell Maven how long to wait before giving up on a connection that has not responded.</p> -<div class="source"><pre class="prettyprint linenums"><settings> + +<div class="source"><pre class="prettyprint linenums"><code><settings> <servers> <server> <id>my-server</id> @@ -213,31 +250,39 @@ </configuration> </server> </servers> -</settings></pre></div> +</settings> +</code></pre></div> <p>These above define per-server timeout configuration, and show default values.</p> <p>These are the standard ways to configure transport, regarding custom headers, and various timeouts. Each transport MAY introduce it's own specific configuration, like we can see below for Wagon.</p></section></section><section> -<h2>Advanced Configuration of the HttpClient HTTP Wagon</h2> -<p>You can use the default wagon implementation for a given protocol, or you can select an alternative wagon <code>provider</code> on a per-protocol basis. For more information, see the <a href="./guide-wagon-providers.html">Guide to Wagon Providers</a> [3]. The default wagon http(s) is the HttpClient based on <a class="externalLink" href="https://hc.apache.org/httpcomponents-client-4.5.x/";>Apache Http Client 4.5</a>. HTTP connection pooling prevents reopening new connections to the same server for each request. This pool feature is configurable with some parameters [4]. The default wagon comes with some default configuration:</p> +<h3>Advanced Configuration of the HttpClient HTTP Wagon</h3> +<p>You can use the default wagon implementation for a given protocol, or you can select an alternative wagon <code>provider</code> on a per-protocol basis. For more information, see the <a href="./guide-wagon-providers.html">Guide to Wagon Providers</a> [3]. The default wagon http(s) is the HttpClient based on <a href="https://hc.apache.org/httpcomponents-client-4.5.x/"; class="externalLink">Apache Http Client 4.5</a>. HTTP connection pooling prevents reopening new connections to the same server for each request. This pool feature is configurable with some parameters [4]. The default wagon comes with some default configuration:</p> <ul> -<li>http(s) connection pool: default to 20.</li> -<li>readTimeout: default to 1,800,000ms (~30 minutes) (see section <code>Read time out</code> below)</li> -<li>default Preemptive Authentication only with PUT (GET doesn't use anymore default Preemptive Authentication)</li></ul><section> -<h3>Introduction</h3> + +<li> +<p>http(s) connection pool: default to 20.</p></li> +<li> +<p>readTimeout: default to 1,800,000ms (~30 minutes) (see section <code>Read time out</code> below)</p></li> +<li> +<p>default Preemptive Authentication only with PUT (GET doesn't use anymore default Preemptive Authentication)</p></li> +</ul><section> +<h4>Introduction</h4> <p>The HttpClient-based HTTP wagon offers more control over the configuration used to access HTTP-based Maven repositories. For starters, you have fine-grained control over what HTTP headers are used when resolving artifacts. In addition, you can also configure a wide range of parameters to control the behavior of HttpClient itself. Best of all, you have the ability to control these headers and parameters for all requests, or individual request types (GET, HEAD, and PUT).</p></section><section> -<h3>The Basics</h3> +<h4>The Basics</h4> <p>Without any special configuration, Maven's HTTP wagon uses some default HTTP headers and client parameters when managing artifacts. The default headers are:</p> -<div> -<pre>Cache-control: no-cache + +<div class="source"><pre class="prettyprint linenums"><code>Cache-control: no-cache Cache-store: no-store Pragma: no-cache Expires: 0 -Accept-Encoding: gzip</pre></div> +Accept-Encoding: gzip +</code></pre></div> <p>In addition, PUT requests made with the HTTP wagon use the following HttpClient parameter:</p> -<div> -<pre>http.protocol.expect-continue=true</pre></div> + +<div class="source"><pre class="prettyprint linenums"><code>http.protocol.expect-continue=true +</code></pre></div> <p>From the HttpClient documentation[2], this parameter provides the following functionality:</p> -<div> -<pre>Activates 'Expect: 100-Continue' handshake for the entity enclosing methods. + +<div class="source"><pre class="prettyprint linenums"><code>Activates 'Expect: 100-Continue' handshake for the entity enclosing methods. The 'Expect: 100-Continue' handshake allows a client that is sending a request message with a request body to determine if the origin server is willing to accept the request (based on the request headers) before the client sends the @@ -248,13 +293,15 @@ improvement for entity enclosing request the target server's authentication. 'Expect: 100-continue' handshake should be used with caution, as it may cause -problems with HTTP servers and proxies that do not support HTTP/1.1 protocol.</pre></div> +problems with HTTP servers and proxies that do not support HTTP/1.1 protocol. +</code></pre></div> <p>Without this setting, PUT requests that require authentication transfer their entire payload to the server before that server issues an authentication challenge. In order to complete the PUT request, the client must then re-send the payload with the proper credentials specified in the HTTP headers. This results in twice the bandwidth usage, and twice the time to transfer each artifact.</p> -<p>Another option to avoid this double transfer is what's known as preemptive authentication, which involves sending the authentication headers along with the original PUT request. However, there are a few potential issues with this approach. For one thing, in the event you have an unused <code><server></code> entry that specifies an invalid username/password combination, some servers may respond with a <code>401 Unauthorized</code> even if the server doesn't actually require any authentication for the request. In addition, blindly sending authentication credentials with every request regardless of whether the server has made a challenge can result in a security hole, since the server may not make provisions to secure credentials for paths that don't require authentication.</p> +<p>Another option to avoid this double transfer is what's known as preemptive authentication, which involves sending the authentication headers along with the original PUT request. However, there are a few potential issues with this approach. For one thing, in the event you have an unused <code>\<server\></code> entry that specifies an invalid username/password combination, some servers may respond with a <code>401 Unauthorized</code> even if the server doesn't actually require any authentication for the request. In addition, blindly sending authentication credentials with every request regardless of whether the server has made a challenge can result in a security hole, since the server may not make provisions to secure credentials for paths that don't require authentication.</p> <p>We'll discuss preemptive authentication in another example, below.</p></section><section> -<h3>Configuring GET, HEAD, PUT, or All of the Above</h3> +<h4>Configuring GET, HEAD, PUT, or All of the Above</h4> <p>In all of the examples below, it's important to understand that you can configure the HTTP settings for all requests made to a given server, or for only one method. To configure all methods for a server, use the following section of the <code>settings.xml</code> file:</p> -<div class="source"><pre class="prettyprint linenums"><settings> + +<div class="source"><pre class="prettyprint linenums"><code><settings> [...] <servers> <server> @@ -268,9 +315,11 @@ problems with HTTP servers and proxies t </configuration> </server> </servers> -</settings></pre></div> +</settings> +</code></pre></div> <p>On the other hand, if you can live with the default configuration for most requests - say, HEAD and GET requests, which are used to check for the existence of a file and retrieve a file respectively - maybe you only need to configure the PUT method:</p> -<div class="source"><pre class="prettyprint linenums"><settings> + +<div class="source"><pre class="prettyprint linenums"><code><settings> [...] <servers> <server> @@ -284,12 +333,14 @@ problems with HTTP servers and proxies t </configuration> </server> </servers> -</settings></pre></div> -<p>For clarity, the other two sections are <code><get></code> for GET requests, and <code><head></code> for HEAD requests. I know that's going to be hard to remember...</p></section><section> -<h3>Taking Control of Your HTTP Headers</h3> -<p>As you may have noticed above, the default HTTP headers do have the potential to cause problems. For instance, some websites set the encoding for downloading GZipped files as <code>gzip</code>, in spite of the fact that the HTTP request itself isn't being sent using GZip compression. If the client is using the <code>Accept-Encoding: gzip</code> header, this can result in the client itself decompressing the GZipped file <i>during the transfer</i> and writing the decompressed file to the local disk with the original filename. This can be misleading to say the least, and can use up an inordinate amount of disk space on the local computer.</p> +</settings> +</code></pre></div> +<p>For clarity, the other two sections are <code>\<get\></code> for GET requests, and <code>\<head\></code> for HEAD requests. I know that's going to be hard to remember…</p></section><section> +<h4>Taking Control of Your HTTP Headers</h4> +<p>As you may have noticed above, the default HTTP headers do have the potential to cause problems. For instance, some websites set the encoding for downloading GZipped files as <code>gzip</code>, in spite of the fact that the HTTP request itself isn't being sent using GZip compression. If the client is using the <code>Accept-Encoding: gzip</code> header, this can result in the client itself decompressing the GZipped file <em>during the transfer</em> and writing the decompressed file to the local disk with the original filename. This can be misleading to say the least, and can use up an inordinate amount of disk space on the local computer.</p> <p>To turn off this default behavior, simply disable the default headers. Then, respecify the other headers that you are still interested in, like this:</p> -<div class="source"><pre class="prettyprint linenums"><settings> + +<div class="source"><pre class="prettyprint linenums"><code><settings> [...] <servers> <server> @@ -327,27 +378,29 @@ problems with HTTP servers and proxies t [...] </servers> [...] -</settings></pre></div></section><section> -<h3>Fine-Tuning HttpClient Parameters</h3> +</settings> +</code></pre></div></section><section> +<h4>Fine-Tuning HttpClient Parameters</h4> <p>Going beyond the power of HTTP request parameters, HttpClient provides a host of other configuration options. In most cases, you won't need to customize these. But in case you do, Maven provides access to specify your own fine-grained configuration for HttpClient. Again, you can specify these parameter customizations per-method (HEAD, GET, or PUT), or for all methods of interacting with a given server. For a complete list of supported parameters, see the link[2] in Resources section below.</p><section> -<h4>Non-String Parameter Values</h4> +<h5>Non-String Parameter Values</h5> <p>Many of the configuration parameters for HttpClient have simple string values; however, there are important exceptions to this. In some cases, you may need to specify boolean, integer, or long values. In others, you may even need to specify a collection of string values. You can specify these using a simple formatting syntax, as follows:</p> -<ol style="list-style-type: decimal"> -<li><b>booleans:</b> <code>%b,<value></code></li> -<li><b>integer:</b> <code>%i,<value></code></li> -<li><b>long:</b> <code>%l,<value></code> (yes, that's an 'L', not a '1')</li> -<li><b>double:</b> <code>%d,<value></code></li> -<li><b>collection of strings:</b> <code>%c,<value1>,<value2>,<value3>,...</code>, which could also be specified as: -<div> -<pre>%c, +<p>1 <strong>booleans:</strong> <code>%b,\<value\></code></p> +<p>1 <strong>integer:</strong> <code>%i,\<value\></code></p> +<p>1 <strong>long:</strong> <code>%l,\<value\></code> (yes, that's an ‘L’, not a ‘1’)</p> +<p>1 <strong>double:</strong> <code>%d,\<value\></code></p> +<p>1 <strong>collection of strings:</strong> <code>%c,\<value1\>,\<value2\>,\<value3\>,...</code>, which could also be specified as:</p> + +<div class="source"><pre class="prettyprint linenums"><code>%c, <value1>, <value2>, <value3>, -...</pre></div></li></ol> +... +</code></pre></div> <p>As you may have noticed, this syntax is similar to the format-and-data strategy used by functions like <code>sprintf()</code> in many languages. The syntax has been chosen with this similarity in mind, to make it a little more intuitive to use.</p></section><section> -<h4>Example: Using Preemptive Authentication</h4> +<h5>Example: Using Preemptive Authentication</h5> <p>Using the above syntax, you can configure preemptive authentication for PUT requests using the boolean HttpClient parameter <code>http.authentication.preemptive</code>, like this:</p> -<div class="source"><pre class="prettyprint linenums"><settings> + +<div class="source"><pre class="prettyprint linenums"><code><settings> <servers> <server> <id>my-server</id> @@ -365,9 +418,11 @@ problems with HTTP servers and proxies t </configuration> </server> </servers> -</settings></pre></div> +</settings> +</code></pre></div> <p>Another option is to make write it like this:</p> -<div class="source"><pre class="prettyprint linenums"><settings> + +<div class="source"><pre class="prettyprint linenums"><code><settings> <servers> <server> <id>my-server</id> @@ -380,12 +435,14 @@ problems with HTTP servers and proxies t </configuration> </server> </servers> -</settings></pre></div></section><section> -<h4>Example: Lifting auth scope restriction for external authentication systems</h4> -<p>Maven Wagon by default limits supplied credentials to the host:port combination scope, ignoring any other target servers. When the target server delegates authentication to an external system, you need to deliberately lift that scope limitation. Configure your server element to pass authentication to all target servers which challenge the client. +---+ <i>settings</i> <i>servers</i> <i>server</i> <i>id</i>my-server<i>/id</i> <i>configuration</i> <i>basicAuthScope</i> <i>host</i>ANY<i>/host</i> <i>port</i>ANY<i>/port</i> <i>!-- or even 443 to force the use of TLS --</i> <i>/basicAuthScope</i> <i>httpConfiguration</i> <i>all</i> <i>params</i> <i>property</i> <i>name</i>http.protocol.cookie-policy<i>/name</i> <i>value</i>standard<i>/value</i> <i>/property</i> <i>/params</i> <i>/all</i> <i>/httpConfiguration</i> <i>/configuration</i> <i>/server</i> <i>/servers</i> <i>/settings</i> +---+</p></section><section> -<h4>Ignoring Cookies</h4> +</settings> +</code></pre></div></section><section> +<h5>Example: Lifting auth scope restriction for external authentication systems</h5> +<p>Maven Wagon by default limits supplied credentials to the host:port combination scope, ignoring any other target servers. When the target server delegates authentication to an external system, you need to deliberately lift that scope limitation. Configure your server element to pass authentication to all target servers which challenge the client. +—+ <em>settings</em> <em>servers</em> <em>server</em> <em>id_my-server</em>/id_ <em>configuration</em> <em>basicAuthScope</em> <em>host_ANY</em>/host_ <em>port_ANY</em>/port_ <em>!– or even 443 to force the use of TLS –</em> <em>/basicAuthScope</em> <em>httpConfiguration</em> <em>all</em> <em>params</em> <em>property</em> <em>name_http.protocol.cookie-policy</em>/name_ <em>value_standard</em>/value_ <em>/property</em> <em>/params</em> <em>/all</em> <em>/httpConfiguration</em> <em>/configuration</em> <em>/server</em> <em>/servers</em> <em>/settings</em> +—+</p></section><section> +<h5>Ignoring Cookies</h5> <p>Like the example above, telling the HttpClient to ignore cookies for all methods of request is a simple matter of configuring the <code>http.protocol.cookie-policy</code> parameter (it uses a regular string value, so no special syntax is required):</p> -<div class="source"><pre class="prettyprint linenums"><settings> + +<div class="source"><pre class="prettyprint linenums"><code><settings> <servers> <server> <id>my-server</id> @@ -403,13 +460,15 @@ problems with HTTP servers and proxies t </configuration> </server> </servers> -</settings></pre></div> +</settings> +</code></pre></div> <p>The configuration above can be useful in cases where the repository is using cookies - like the session cookies that are often mistakenly turned on or left on in appservers - alongside HTTP redirection. In these cases, it becomes far more likely that the cookie issued by the appserver uses a <code>Path</code> that is inconsistent with the one used by the client to access the server. If you have this problem, and know that you don't need to use this session cookie, you can ignore cookies from this server with the above configuration.</p></section></section><section> -<h3>Support for General-Wagon Configuration Standards</h3> +<h4>Support for General-Wagon Configuration Standards</h4> <p>It should be noted that configuration options previously available in the HttpClient-driven HTTP wagon are still supported in addition to this new, fine-grained approach. These include the configuration of HTTP headers and connection timeouts. Let's examine each of these briefly:</p><section> -<h4>HTTP Headers</h4> +<h5>HTTP Headers</h5> <p>In all HTTP Wagon implementations, you can add your own HTTP headers like this:</p> -<div class="source"><pre class="prettyprint linenums"><settings> + +<div class="source"><pre class="prettyprint linenums"><code><settings> <servers> <server> <id>my-server</id> @@ -423,11 +482,13 @@ problems with HTTP servers and proxies t </configuration> </server> </servers> -</settings></pre></div> +</settings> +</code></pre></div> <p>It's important to understand that the above approach doesn't allow you to turn off all of the default HTTP headers; nor does it allow you to specify headers on a per-method basis. However, this configuration remains available in both the lightweight and httpclient-based Wagon implementations.</p></section><section> -<h4>Connection Timeouts</h4> +<h5>Connection Timeouts</h5> <p>All wagon implementations that extend the <code>AbstractWagon</code> class, including those for SCP, HTTP, FTP, and more, allow the configuration of a connection timeout, to allow the user to tell Maven how long to wait before giving up on a connection that has not responded. This option is preserved in the HttpClient-based wagon, but this wagon also provides a fine-grained alternative configuration that can allow you to specify timeouts per-method for a given server. The old configuration option - which is still supported - looks like this:</p> -<div class="source"><pre class="prettyprint linenums"><settings> + +<div class="source"><pre class="prettyprint linenums"><code><settings> <servers> <server> <id>my-server</id> @@ -436,9 +497,11 @@ problems with HTTP servers and proxies t </configuration> </server> </servers> -</settings></pre></div> -<p>...while the new configuration option looks more like this:</p> -<div class="source"><pre class="prettyprint linenums"><settings> +</settings> +</code></pre></div> +<p>…while the new configuration option looks more like this:</p> + +<div class="source"><pre class="prettyprint linenums"><code><settings> <servers> <server> <id>my-server</id> @@ -451,11 +514,13 @@ problems with HTTP servers and proxies t </configuration> </server> </servers> -</settings></pre></div> -<p>If all you need is a per-server timeout configuration, you still have the option to use the old <code><timeout></code> parameter. If you need to separate timeout preferences according to HTTP method, you can use one more like that specified directly above.</p></section><section> -<h4>Read time out</h4> +</settings> +</code></pre></div> +<p>If all you need is a per-server timeout configuration, you still have the option to use the old <code>\<timeout\></code> parameter. If you need to separate timeout preferences according to HTTP method, you can use one more like that specified directly above.</p></section><section> +<h5>Read time out</h5> <p>With Wagon 2.0 and Apache Maven 3.0.4, a default timeout of 30 minutes comes by default. If you want to change this value, you can add the following setup in your settings:</p> -<div class="source"><pre class="prettyprint linenums"><settings> + +<div class="source"><pre class="prettyprint linenums"><code><settings> <servers> <server> <id>my-server</id> @@ -468,13 +533,13 @@ problems with HTTP servers and proxies t </configuration> </server> </servers> -</settings></pre></div></section></section><section> -<h3>Resources</h3> -<ol style="list-style-type: decimal"> -<li><a class="externalLink" href="https://hc.apache.org/httpcomponents-client-4.5.x/";>HttpClient website</a></li> -<li><a class="externalLink" href="https://hc.apache.org/httpclient-3.x/preference-api.html";>HttpClient preference architecture and configuration guide</a></li> -<li><a href="./guide-wagon-providers.html">Guide to Wagon Providers</a></li> -<li><a href="/wagon/wagon-providers/wagon-http/">Wagon Http</a></li></ol></section></section></section> +</settings> +</code></pre></div></section></section><section> +<h4>Resources</h4> +<p>1 <a href="https://hc.apache.org/httpcomponents-client-4.5.x/"; class="externalLink">HttpClient website</a></p> +<p>1 <a href="https://hc.apache.org/httpclient-3.x/preference-api.html"; class="externalLink">HttpClient preference architecture and configuration guide</a></p> +<p>1 <a href="./guide-wagon-providers.html">Guide to Wagon Providers</a></p> +<p>1 <a href="/wagon/wagon-providers/wagon-http/">Wagon Http</a></p></section></section></section></section> </main> </div> </div> Modified: maven/website/content/guides/mini/guide-large-scale-centralized-deployments.html ============================================================================== --- maven/website/content/guides/mini/guide-large-scale-centralized-deployments.html (original) +++ maven/website/content/guides/mini/guide-large-scale-centralized-deployments.html Thu Feb 9 00:34:05 2023 @@ -2,7 +2,7 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/mini/guide-large-scale-centralized-deployments.apt at 2023-02-08 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/markdown/guides/mini/guide-large-scale-centralized-deployments.md at 2023-02-09 | Rendered using Apache Maven Fluido Skin 1.11.1 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang=""> @@ -48,8 +48,8 @@ <ul class="breadcrumb"> <li class=""><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li class=""><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - <li class="active ">Guide to Large Scale Centralized Deployments <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/mini/guide-large-scale-centralized-deployments.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> - <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2023-02-08</li> + <li class="active ">Guide to Large Scale Centralized Deployments <a href="https://github.com/apache/maven-site/tree/master/content/markdown/guides/mini/guide-large-scale-centralized-deployments.md";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2023-02-09</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> <li class="pull-right"><a href="../../download.cgi" title="Download">Download</a></li> @@ -152,42 +152,70 @@ </div> </header> <main id="bodyColumn" class="span10" > -<section> -<h1>Guide to Large Scale Centralized Deployments</h1> +<!-- +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. +--> +<section><section> +<h2>Guide to Large Scale Centralized Deployments</h2> <p>This guide covers a simple optimized approach to using a <a href="../../repository-management.html">repository manager</a> in a large organization with hundreds/thousands of Maven projects.</p> <p>The pillars of this approach are:</p> -<ol style="list-style-type: decimal"> -<li>Use a centralized <a href="../../repository-management.html">repository manager</a>. +<p>1 Use a centralized <a href="../../repository-management.html">repository manager</a>.</p> <ul> -<li>Maven clients should download needed artifacts from the repository manager.</li> -<li>Maven clients should upload proprietary artifacts to the repository manager.</li></ul></li> -<li>Configure the location to download/upload artifacts in Maven <code>settings.xml</code> files, rather than in <code>pom.xml</code> files.</li> -<li>Centrally manage the <code>settings.xml</code> files, and distribute them via automation.</li></ol><section> -<h2><a id="Repository_Manager_Layout">Repository Manager Layout</a></h2> + +<li> +<p>Maven clients should download needed artifacts from the repository manager.</p></li> +<li> +<p>Maven clients should upload proprietary artifacts to the repository manager.</p></li> +</ul> +<p>1 Configure the location to download/upload artifacts in Maven <code>settings.xml</code> files, rather than in <code>pom.xml</code> files.</p> +<p>1 Centrally manage the <code>settings.xml</code> files, and distribute them via automation.</p><section> +<h3>Repository Manager Layout</h3> <p>Repository managers generally have at least three types of repositories:</p> -<dl> -<dt>hosted</dt> -<dd>contains artifacts uploaded to the repository manager</dd> -<dt>proxy</dt> -<dd>proxies a remote repository and caches artifacts</dd> -<dt>virtual</dt> -<dd>aggregates several repositories into one</dd></dl> +<p>[hosted] contains artifacts uploaded to the repository manager</p> +<p>[proxy] proxies a remote repository and caches artifacts</p> +<p>[virtual] aggregates several repositories into one</p> <p>The simplest way to organize repositories within a repository manager is to have a single virtual repository that aggregates:</p> <ul> -<li>a proxy repository for each public repository to mirror. (For example: Maven Central)</li> -<li>a hosted repository for releases</li> -<li>a hosted repository for snapshots</li> -<li>a hosted repository that can contain both releases and snapshots (Only needed if some projects are still using Maven Deploy Plugin < 2.8. See <a href="#Managing_Uploads_to_the_Repository_Manager">Managing Uploads to the Repository Manager</a> for more info.)</li></ul> + +<li> +<p>a proxy repository for each public repository to mirror. (For example: Maven Central)</p></li> +<li> +<p>a hosted repository for releases</p></li> +<li> +<p>a hosted repository for snapshots</p></li> +<li> +<p>a hosted repository that can contain both releases and snapshots (Only needed if some projects are still using Maven Deploy Plugin < 2.8. See <a href="Managing_Uploads_to_the_Repository_Manager">Managing Uploads to the Repository Manager</a> for more info.)</p></li> +</ul> <p>Separate hosted repositories are generally used for releases and snapshots due to the need for different artifact retention policies.</p> <p>The following sections describe how to configure Maven clients to:</p> <ul> -<li><a href="#Managing_Downloads_from_the_Repository_Manager">Download</a> artifacts from the virtual repository.</li> -<li><a href="#Managing_Uploads_to_the_Repository_Manager">Upload</a> artifacts to one of the hosted repositories.</li></ul></section><section> -<h2><a id="Managing_Downloads_from_the_Repository_Manager">Managing Downloads from the Repository Manager</a></h2> + +<li> +<p><a href="Managing_Downloads_from_the_Repository_Manager">Download</a> artifacts from the virtual repository.</p></li> +<li> +<p><a href="Managing_Uploads_to_the_Repository_Manager">Upload</a> artifacts to one of the hosted repositories.</p></li> +</ul></section><section> +<h3>Managing Downloads from the Repository Manager</h3> <p>All artifacts used by Maven projects in the organization should be downloaded from the single virtual repository of the repository manager.</p> <p>Maven can be instructed to download artifacts from the repository manager's virtual repository by defining a mirror in the Maven <code>settings.xml</code> file as described in the <a href="./guide-mirror-settings.html">Guide to Mirror Settings</a>.</p> <p>Example: To download artifacts from the corporate repository manager's <code>maven-virtual</code> repository:</p> -<div class="source"><pre class="prettyprint linenums"><settings> + +<div class="source"><pre class="prettyprint linenums"><code><settings> ... <mirrors> <!-- Mirror all external repositories via the Corporate Repository Manager's Maven virtual repository --> @@ -199,15 +227,17 @@ </mirror> </mirrors> ... -</settings></pre></div></section><section> -<h2><a id="Managing_Uploads_to_the_Repository_Manager">Managing Uploads to the Repository Manager</a></h2> +</settings> +</code></pre></div></section><section> +<h3>Managing Uploads to the Repository Manager</h3> <p>All proprietary artifacts produced by Maven projects in the organization should be uploaded to the repository manager's hosted repositories.</p> -<p>The <a href="../../plugins/maven-deploy-plugin">Maven Deploy Plugin</a> can be instructed to upload artifacts to the repository manager's repositories by defining the <code>alt*DeploymentRepository</code> properties in the Maven <code>settings.xml</code> file. When these properties are defined, the Maven Deploy Plugin's <a href="../../plugins/maven-deploy-plugin/deploy-mojo.html">deploy</a> goal uses them instead of the <code><distributionManagement></code> section of <code>pom.xml</code> files to determine where to upload artifacts.</p> -<p>Defining the upload destination of artifacts in <code>settings.xml</code> files rather than in the <code><distributionManagement></code> section of <code>pom.xml</code> files allows the destinations to be centrally managed, which simplifies maintenance if the destinations need to change. In other words, rather than changing a huge number of <code>pom.xml</code> files, you just need to change <a href="#Settings_File_Locations">relatively few</a> <code>settings.xml</code> files if/when the distribution locations need to change.</p> +<p>The <a href="../../plugins/maven-deploy-plugin">Maven Deploy Plugin</a> can be instructed to upload artifacts to the repository manager's repositories by defining the <code>alt\*DeploymentRepository</code> properties in the Maven <code>settings.xml</code> file. When these properties are defined, the Maven Deploy Plugin's <a href="../../plugins/maven-deploy-plugin/deploy-mojo.html">deploy</a> goal uses them instead of the <code>\<distributionManagement\></code> section of <code>pom.xml</code> files to determine where to upload artifacts.</p> +<p>Defining the upload destination of artifacts in <code>settings.xml</code> files rather than in the <code>\<distributionManagement\></code> section of <code>pom.xml</code> files allows the destinations to be centrally managed, which simplifies maintenance if the destinations need to change. In other words, rather than changing a huge number of <code>pom.xml</code> files, you just need to change <a href="Settings_File_Locations">relatively few</a> <code>settings.xml</code> files if/when the distribution locations need to change.</p> <p>The ability to specify separate alternate deployment repositories for releases and snapshots via the <code>altReleaseDeploymentRepository</code> and <code>altSnapshotDeploymentRepository</code> properties, respectively, was added in Maven Deploy Plugin 2.8. To get the most out of the approach defined in this document, all projects should use Maven Deploy Plugin >=2.8. If some projects are still using an older version of Maven Deploy Plugin (>=2.3 and <2.8), then specify a single alternate deployment repository via the <code>altDeploymentRepository</code> property that points to a repository capable of containing both releases and snapshots.</p> <p>Typically, only continuous integration servers are allowed to upload artifacts to the repository manager. Therefore, these settings should only be specified in <code>settings.xml</code> files on continuous integration servers, and should not be in <code>settings.xml</code> files on developer machines. Alternatively, if you want developers to be able to upload artifacts to the repository manager, then include these properties in the <code>settings.xml</code> files used by developers.</p> <p>Example: To upload artifacts to one of the corporate repository manager's hosted repositories:</p> -<div class="source"><pre class="prettyprint linenums"><settings> + +<div class="source"><pre class="prettyprint linenums"><code><settings> ... <profiles> <profile> @@ -282,15 +312,20 @@ <activeProfile>corp-repository-manager</activeProfile> </activeProfiles> ... -</settings></pre></div></section><section> -<h2><a id="Settings_File_Locations">Settings File Locations</a></h2> +</settings> +</code></pre></div></section><section> +<h3>Settings File Locations</h3> <p>Maven <code>settings.xml</code> files need to be available wherever Maven builds are performed, typically:</p> <ul> -<li>on continuous integration servers, and</li> -<li>on developer machines</li></ul> -<p>Both locations should have the mirror settings mentioned in <a href="#Managing_Downloads_from_the_Repository_Manager">Managing Downloads from the Repository Manager</a>.</p> -<p>Typically, only continuous integration servers should have the deployment repository settings mentioned in <a href="#Managing_Uploads_to_the_Repository_Manager">Managing Uploads to the Repository Manager</a>, because only continuous integration servers should be allowed to upload to the repository manager. Alternatively, if you want developers to be able to upload artifacts to the repository manager, then include the deployment repository properties in the <code>settings.xml</code> files used by developers.</p> -<p>How the <code>settings.xml</code> files are stored and updated is beyond the scope of this document. The general recommendation is to manage a few <code>settings.xml</code> files centrally, and then use automation to distribute them to continuous integration servers and developer machines.</p></section></section> + +<li> +<p>on continuous integration servers, and</p></li> +<li> +<p>on developer machines</p></li> +</ul> +<p>Both locations should have the mirror settings mentioned in <a href="Managing_Downloads_from_the_Repository_Manager">Managing Downloads from the Repository Manager</a>.</p> +<p>Typically, only continuous integration servers should have the deployment repository settings mentioned in <a href="Managing_Uploads_to_the_Repository_Manager">Managing Uploads to the Repository Manager</a>, because only continuous integration servers should be allowed to upload to the repository manager. Alternatively, if you want developers to be able to upload artifacts to the repository manager, then include the deployment repository properties in the <code>settings.xml</code> files used by developers.</p> +<p>How the <code>settings.xml</code> files are stored and updated is beyond the scope of this document. The general recommendation is to manage a few <code>settings.xml</code> files centrally, and then use automation to distribute them to continuous integration servers and developer machines.</p></section></section></section> </main> </div> </div> Modified: maven/website/content/guides/mini/guide-manifest.html ============================================================================== --- maven/website/content/guides/mini/guide-manifest.html (original) +++ maven/website/content/guides/mini/guide-manifest.html Thu Feb 9 00:34:05 2023 @@ -2,7 +2,7 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/mini/guide-manifest.apt at 2023-02-08 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/markdown/guides/mini/guide-manifest.md at 2023-02-09 | Rendered using Apache Maven Fluido Skin 1.11.1 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang=""> @@ -10,8 +10,7 @@ <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M4" /> - <meta name="author" content="Jason van Zyl -Dennis Lundberg" /> + <meta name="author" content="Jason van Zyl, Dennis Lundberg" /> <meta name="date" content="2010-08-19" /> <title>Maven – Guide to Working with Manifests</title> <link rel="stylesheet" href="../../css/apache-maven-fluido-1.11.1.min.css" /> @@ -49,8 +48,8 @@ Dennis Lundberg" /> <ul class="breadcrumb"> <li class=""><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li class=""><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - <li class="active ">Guide to Working with Manifests <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/mini/guide-manifest.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> - <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2023-02-08</li> + <li class="active ">Guide to Working with Manifests <a href="https://github.com/apache/maven-site/tree/master/content/markdown/guides/mini/guide-manifest.md";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2023-02-09</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> <li class="pull-right"><a href="../../download.cgi" title="Download">Download</a></li> @@ -155,9 +154,34 @@ Dennis Lundberg" /> </div> </header> <main id="bodyColumn" class="span10" > -<section> -<h1>Guide to Working with Manifests</h1> -<p>In order to modify the manifest of the archive produced by the packaging plug-ins you need to create a configuration for it. The definitive guide for this is <a href="/shared/maven-archiver/index.html">the site for the Maven Archiver shared component</a>. This component is used by all our packaging plugins.</p></section> +<!-- +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. +--> +<section><section> +<h2>Guide to Working with Manifests</h2> +<p>In order to modify the manifest of the archive produced by the packaging plug-ins you need to create a configuration for it. The definitive guide for this is <a href="/shared/maven-archiver/index.html">the site for the Maven Archiver shared component</a>. This component is used by all our packaging plugins.</p><!-- suggestion by jorg --> +<!-- it would be nice if the Specification-Version could be easily generated to be major.minor of pom.currentVersion i.e. that --> +<!-- --> +<!-- 1.2 ==> 1.2 --> +<!-- 1.2.1 ==> 1.2 --> +<!-- 1.2-SNAPSHOT ==> 1.2 --> +<!-- for the javaapp-plugin I did something like this in Jelly ... --> +</section></section> </main> </div> </div>
