Understanding Repository Configuration of Apache Archiva

; Wed, 19 Sep 2012 13:36:42 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r1387592 [4/14] - in /archiva/site-content/docs/1.4-M2: ./ adminguide/ adminguide/webservices/ css/ customising/ images/ images/fancybox/ images/logos/ images/tour/ js/ tour/ userguide/ Date: Wed, 19 Sep 2012 13:36:39 -0000 To: commits@archiva.apache.org From: olamy@apache.org X-Mailer: svnmailer-1.0.8-patched Message-Id: <20120919133642.EF1BA2388B4E@eris.apache.org> Added: archiva/site-content/docs/1.4-M2/adminguide/repositories.html URL: http://svn.apache.org/viewvc/archiva/site-content/docs/1.4-M2/adminguide/repositories.html?rev=1387592&view=auto ============================================================================== --- archiva/site-content/docs/1.4-M2/adminguide/repositories.html (added) +++ archiva/site-content/docs/1.4-M2/adminguide/repositories.html Wed Sep 19 13:36:34 2012 @@ -0,0 +1,254 @@ + + + + + + Understanding Repository Configuration of Apache Archiva + + + + + + + + + + + + + + + + + + + + + + + + + +

+ + +

+ +

+ + + +

+ +

Understanding Repository Configuration of Apache Archiva

Archiva has two types of repository configuration: managed repository and remote repository.

Managed Repository

A managed repository is a repository which resides locally to the server where Archiva is running. It could serve as a proxy repository, an internal deployment repository or a local mirror repository.

Managed repository fields:

identifier - the id of the repository. This must be unique.
name - the name of the repository.
directory - the location of the repository. If the path specified does not exist, Archiva will create the missing directories.
index directory - the location of the index files generated by Archiva. If no location is specified, then the index directory (named .indexer) will be created at the root of the repository directory. Another directory named .index is also created at the root of the repository directory. This is not configurable though as it contains the packaged/bundled index which is consumed by different consumers of the index such as M2Eclipse.
type - the repository layout (maven 2 or maven 1)
cron - the cron schedule when repository scanning will be executed.
repository purge by days older - the first option for repository purge. Archiva will check how old the artifact is and if it is older than the set number of days in this field, then the artifact will be deleted respecting the retention count (see #7) of course. In order to disable the purge by number of days old and set Archiva to purge by retention count, just set the repository purge field to 0. The maximum number of days which can be set here is 1000. See the Repository Purge section below for more details.
repository purge by retention count - the second option for repository purge. When running the repository purge, Archiva will retain only the number of artifacts set for this field for a specific snapshot version. See the Repository Purge section below for more details.
releases included - specifies whether there are released artifacts in the repository.
block re-deployment of released artifacts - specifies whether released artifacts that are already existing in the repository can be overwritten. Note that this only take effects for non-snapshot deployments.
snapshots included - specifies whether there are snapshot artifacts in the repository.
scannable - specifies whether the repository can be sc anned, meaning it is a local repository which can be indexed, browsed, purged, etc.
delete released snapshots - specifies whether to remove those snapshot artifacts which already has release versions of it in the repository during repository purge.

Each repository has its own Webdav url. This allows the user to browse and access the repository via webdav. The url has the following format:

http://[URL TO ARCHIVA]/repository/[REPOSITORY ID] (e.g. http://localhost:8080/archiva/repository/releases).

A pom snippet is also available for each repository. The <distributionManagement> section can be copied and pasted into a project's pom to specify that the project will be deployed in that managed repository. The <repositories> section on the other hand, can be copied and pasted to a project's pom.xml or to Maven's settings.xml to tell Maven to get artifacts from the managed reposit ory when building the project.

Remote Repository

A remote repository is a repository which resides remotely. These repositories are usually the proxied repositories. See Proxy Connectors on how to proxy a repository.

Remote repository fields:

identifier - the id of the remote repository.
name - the name of the remote repository.
url - the url of the remote repository. It is also possible to use a 'file://' url to proxy a local repository. Be careful that if this local repository is a managed repository of archiva which has some proxies connectors, those ones won't be triggered.
username - the username (if authentication is needed) to be used to access the repository.
password - the password (if authentication is needed) to be used to access the repository.
type - the layout (maven 2 or maven 1) of the r emote repository.
Activate download remote index - to activate downloading remote index to add available remote artifacts in search queries.
Remote index url, can be relative to url - path of the remote index directory.
Cron expression - cron expression for downloading remote index (default weekly on sunday)
Directory index storage - path to store index directory, default will be $appserver.base/data/remotes/$repositoryId/.index
Download Remote Index Timeout in seconds - read time out for downloading remote index files (default 300)
Network Proxy to Use for download Remote Index - proxy to use for downloading remote index files.
You can also trigger an immediate download of remote index files.

Scanning a Repository

Repository scan can be executed on schedule or it can be explicitly executed by clicking the 'Scan Repository Now' button in the repositories page. By default, Archiva only processes new artifacts in the repository with respect to the last run of the repository scanner. Meaning that if the artifact's last modified date is newer than the last repository scan, then the artifact will be processed. Otherwise, it will be skipped. You can override this behavior and force Archiva to process all artifacts regardless of its age by ticking the 'Process All Artifacts' checkbox in the repositories page and clicking the 'Scan Repository Now' button.

For every artifact found by the repository scanner, processing is done on this artifact by different consumers. Examples of the processing done are: indexing, repository purge and database update. Details about consumers are available in the Consumers page.

Repository Purge

Repository purge is the process of cleaning up the repository of old snapshots. When deploying a snapshot to a repository, Maven deploys the project/artifact with a timestamped version. Doing daily/nightly builds of the project then tends to bloat the repository. What if the artifact is large? Then disk space will definitely be a problem. That's where Archiva's repository purge feature comes in. Given a criteria to use -- by the number of days old and by retention count, it would clean up the repository by removing old snapshots.

Please take note that the by number of days old criteria is activated by default (set to 100 days). In order to de-activate it and use the by retention count criteria, you must set the Repository Purge By Days Older field to 0. Another thing to note here is that if the by number of days old criteria is activated, the retention count would still be respected (See the Repository Purge By Days Older section below for more details) but not the other way around.

Let's take a look at different behaviours for repository purge using the following scenario:

Artifacts in the repository:
+
+../artifact-x/2.0-SNAPSHOT/artifact-x-20061118.060401-2.jar
+../artifact-x/2.0-SNAPSHOT/artifact-x-20061118.060401-2.pom
+../artifact-x/2.0-SNAPSHOT/artifact-x-20070113.034619-3.jar
+../artifact-x/2.0-SNAPSHOT/artifact-x-20070113.034619-3.pom
+../artifact-x/2.0-SNAPSHOT/artifact-x-20070203.028902-4.jar
+../artifact-x/2.0-SNAPSHOT/artifact-x-20070203.028902-4.pom

Repository Purge By Number of Days Older
Using this criteria for the purge, Archiva will check how old an artifact is and if it is older than the set value in the repository purge by days older field, then the artifact will be deleted respecting the retention count of course.
If repository purge by days older is set to 100 days (with repository purge by retention count field set to 1), and the current date is let's say 03-01-2007, given the scenario above.. the following artifacts will be retained: artifact-x-20070113.034619-3.jar, artifact-x-20070113.034619-3.pom, artifact-x-20070203.028902-4.jar and artifact-x-20070203.028902-4.pom. It is clear in the version timestamps that these 4 artifacts are not more than 100 days old from the current date (which is 03-01-2007 in our example) so they are all retained. In this case the retention count doesn't have any effect since the priority is the age of the artifact.
Now, if the repository purge by days older is set to 30 days (with repository purge by retention count field still set to 1) and the current date is still 03-01-2007, then given the same scenario above.. only the following artifacts will be retained: artifact-x-20070203.028902-4.jar and artifact-x-20070203.028902-4.pom. In this case, we can see that the retained artifacts are still not older by the number of days set in the repository purge by days older field and the retention count is still met.
Now, let's set the repository purge by days older to 10 days (with repository purge by retention count field still set to 1) and the current date is still 03-01-2007, then still given the same repository contents above.. the following artifacts will still be retained: artifact-x-20070203.028902-4.jar and artifact-x-20070203.028902-4.pom. It is clear from the version timestamps that the artifacts ARE MORE THAN the r epository purge by days older value, which is 10 days. Why is it still retained? Recall the value of the repository purge by retention count -- 1 :) This ensures that there is ALWAYS 1 artifact timestamped version retained for every unique version snapshot directory of an artifact.
Repository Purge By Retention Count
If the repository purge by retention count field is set to 2, then only the artifacts artifact-x-20070113.034619-3.jar, artifact-x-20070113.034619-3.pom, artifact-x-20070203.028902-4.jar and artifact-x-20070203.028902-4.pom will be retained in the repository. The oldest snapshots will be deleted maintaining only a number of snapshots equivalent to the set retention count (regardless of how old or new the artifact is).

Deleting Released Snapshots

You can also configure Archiva to clean up snapshot artifacts that have already been released. This can be done by tic king the Delete Released Snapshots checkbox in the Repository Configuration form.

Once this feature is enabled, if Archiva encounters a snapshot artifact during repository scanning, it would check all the repositories configured for a released version of that snapshot. If it finds one, then it would delete the entire snapshot version directory.

It should be noted that this feature is entirely separate from the repository purge by number of days older and by retention count.

+ + + + Added: archiva/site-content/docs/1.4-M2/adminguide/roles.html URL: http://svn.apache.org/viewvc/archiva/site-content/docs/1.4-M2/adminguide/roles.html?rev=1387592&view=auto ============================================================================== --- archiva/site-content/docs/1.4-M2/adminguide/roles.html (added) +++ archiva/site-content/docs/1.4-M2/adminguide/roles.html Wed Sep 19 13:36:34 2012 @@ -0,0 +1,229 @@ + + + + + + Understanding Apache Archiva Security Roles + + + + + + + + + + + + + + + + + + + + + + + +

+ + +

+ +

+ + +

Introduction

Users Guide

ASF

Project Documentation

+ Project Information +

+ + + + +

+ +

+ +

Understanding Apache Archiva Security Roles

Archiva uses the Redback security framework for managing repository security. When the server is first started, you will be prompted to create an administration user. This user will be given permission to administer all aspects of the system (as well as access to all of the repositories). This user can then be used to grant permissions to other users.

A guest user is also created by default, and given read access to the default repositories (internal and snapshots). Repositories with guest user access can be accessed without the use of a username and password (or without being logged in to the web interface).

However, when new repositories are created, by default no permissions are assigned and only the administrators will have access until it is explicitly granted.

Note that Redback has the concept of inferred roles, so the assignment of s ome roles will imply other roles (which will be displayed in the web interface).

Repository Roles

Archiva contains the following roles for repository access:

Repository Observer: users with this role can read from the given repository that the role is for (including access through the browse and search features of the web interface)
Repository Manager: users with this role can write to and administer the given repository that the role is for
Global Repository Observer: users with this role can read from any repository (including access through the browse and search features of the web interface)
Global Repository Manager: users with this role can write to and administer any repository in the instance

General Roles

Archiva also contains the following general roles for securit y of the instance:

System Administrator: full access to all functionality in the system
User Administrator: ability to create, edit, and grant roles to other users in the system

The guest and registered user roles do not affect repository access.

+ + + + Added: archiva/site-content/docs/1.4-M2/adminguide/security-logs.html URL: http://svn.apache.org/viewvc/archiva/site-content/docs/1.4-M2/adminguide/security-logs.html?rev=1387592&view=auto ============================================================================== --- archiva/site-content/docs/1.4-M2/adminguide/security-logs.html (added) +++ archiva/site-content/docs/1.4-M2/adminguide/security-logs.html Wed Sep 19 13:36:34 2012 @@ -0,0 +1,236 @@ + + + + + + Security Logs + + + + + + + + + + + + + + + + + + + + + + + + +

+ + +

+ +

+ + +

Introduction

Users Guide

Administrators Guide

+ Installing Archiva +
+ Databases +
+ Repositories Content Storage +
+ Security +
+ Runtime Configuration +
+ Configuration Files +
+ Log Files +
- + Archiva Logs +
- + Audit Logs +
- + Security Logs +
+
+ Reports +
+ Web Services +
- + Xml Rpc +
- + REST +
+

Customising Archiva

+ Writing a Consumer Plugin +

More Information

+ Archiva Wiki +

ASF

Project Documentation

+ Project Information +

+ + + + +

+ +

Security Logs

Archiva's logs directory contains a security log file named archiva-security-audit.log, which keeps track of all the security operations such as user creation/deletion, user role assignments, and user log in/out.

A typical record looks like this:

2009-07-22 12:03:11 -  - Successful Login for user admin
+2009-07-22 12:05:03 - admin - User Created: archiva
+2009-07-22 12:05:25 - admin - Role Assigned to user archiva: Global Repository Manager
+2009-07-22 12:05:33 - admin - User Modified: archiva

The hyphen delimited records are:

date and time (server local time)
current user performing the operation
the operation performed

Currently, the following events are logged:

user creation/modification/deletion
user log in/out
assigning roles to a user

+ + + + Added: archiva/site-content/docs/1.4-M2/adminguide/security.html URL: http://svn.apache.org/viewvc/archiva/site-content/docs/1.4-M2/adminguide/security.html?rev=1387592&view=auto ============================================================================== --- archiva/site-content/docs/1.4-M2/adminguide/security.html (added) +++ archiva/site-content/docs/1.4-M2/adminguide/security.html Wed Sep 19 13:36:34 2012 @@ -0,0 +1,229 @@ + + + + + + Understanding Apache Archiva Security + + + + + + + + + + + + + + + + + + + + + + + +

+ + +

+ +

+ + +

Introduction

Users Guide

Administrators Guide

+ Installing Archiva +
+ Databases +
+ Repositories Content Storage +
+ Security +
- + Roles +
- + Customising +
+
+ Runtime Configuration +
+ Configuration Files +
+ Log Files +
+ Reports +
+ Web Services +
- + Xml Rpc +
- + REST +
+

Customising Archiva

+ Writing a Consumer Plugin +

More Information

+ Archiva Wiki +

ASF

Project Documentation

+ Project Information +

+ + + + +

+ +

Understanding Apache Archiva Security

Archiva's security is managed by Redback. The following document describes how to configure your repository security:

+ + + + Added: archiva/site-content/docs/1.4-M2/adminguide/staging-repositories.html URL: http://svn.apache.org/viewvc/archiva/site-content/docs/1.4-M2/adminguide/staging-repositories.html?rev=1387592&view=auto ============================================================================== --- archiva/site-content/docs/1.4-M2/adminguide/staging-repositories.html (added) +++ archiva/site-content/docs/1.4-M2/adminguide/staging-repositories.html Wed Sep 19 13:36:34 2012 @@ -0,0 +1,244 @@ + + + + + + Staging Repositories + + + + + + + + + + + + + + + + + + + + + + + +

+ + +

+ +

+ + +

Introduction

Users Guide

Administrators Guide

+ Installing Archiva +
+ Databases +
+ Repositories Content Storage +
+ Security +
+ Runtime Configuration +
- + Repositories +
- + Proxy Connectors +
- + Network Proxies +
- + Network Configuration +
- + Legacy (Maven 1) Support +
- + Consumers +
- + Staging Repositories +
+
+ Configuration Files +
+ Log Files +
+ Reports +
+ Web Services +
- + Xml Rpc +
- + REST +
+

Customising Archiva

+ Writing a Consumer Plugin +

More Information

+ Archiva Wiki +

ASF

Project Documentation

+ Project Information +

+ + + + +

+ +

Staging Repositories

Starting w ith Archiva 1.4, staging repositories are supported. A staging repository is a repository you use to stage a release (while it undergoes testing and voting), before the release is officially announced and published to a releases repository where users can obtain it.

With the support of staging repositories comes the ability to merge repositories from the web UI. By merging, we mean promoting the artifacts in the staging repository to the managed repository. In the current implementation, a user with the System Administrator role can create and attach a staging repository to an existing managed repository. An attached staging repository is a shadow of its managed repository, meaning they have the same configuration.

We append -stage to the managed repository's ID to identify its staging repository. For example, repository test would have a staging repository called test-stage.

If you're creating a new managed repository, just tick th e Create stage repository check box. Otherwise, if you already have an existing managed repository and you want to create a staging repository, just edit the managed repository's configuration and tick the Create stage repository checkbox, then save the configuration. A staging repository directory will be created beside (as a sibling of) the managed repository directory, again with -stage appended to the name.

Note: By un-ticking the Create stage repository checkbox, the user can delete the attached staging repository. If the managed repository is deleted, then its attached staging repository is also deleted.

The default snapshots and internal repositories do not have staging repositories configured by default, however they can be added by editing the repository configuration.

Populating the Staging Repository

The staging repos itory can be populated in the same way as a normal managed repository. You can configure your Maven build's distributionManagement section to deploy to the repository, or use Archiva's web-based upload feature.

Merging Repositories

To merge or promote the artifacts in a staging repository to the managed repository, just click the Merge button in the repository configuration page.

Archiva will check for conflicting artifacts between the two repositories, and list them (if it finds conflicts). The user will be asked to choose between two actions:

Merge All - ignore all conflicting artifacts and perform merging for all.
Merge With Skip - skip all conflicting artifacts and merge only the non-conflicting ones.

In future, we plan to enhance this by allowing a user to select only specific artifacts to merge.

+ + + +