Configure Receiving-Only Mode

Configure a Federation member to operate in receiving-only (unidirectional sync) mode. When selected, the repository receives events and binaries from other Federation members but cannot send. This option maintains a central source of truth while enabling access to artifacts in distributed environments. It serves as a more reliable, highly scalable replacement for legacy Push Replication by enforcing strict hub-and-spoke architectures with clear ownership, minimizing storage costs and network traffic by preventing unwanted artifact replication from remote spokes back to the central hub.

Primary Benefits

• Governance and compliance: Keep satellite or third-party sites in a receive-only posture.
• Operational simplicity: Use federation's streaming, auto-healing, and observability instead of the job-scheduling overhead of replication.
• Deterministic hub-and-spoke: Enforce source-to-target flows with clear ownership, minimizing storage costs and network traffic by preventing unwanted artifact replication from remote spokes back to the central hub.

How Transmission Mode Works

• bidirectional (default): members send and receive. See Mirror Modes for more on bidirectional and receiver behavior.
• receiver: the member is receive-only within that repository's federation. Outbound federation processing and Full Sync initiation are skipped for the receiver. On the JPD where this member is configured, the federated repository is read-only and local write operations are blocked. Monitoring (Federation Status, connection states) reflects Receiving Only semantics for that member.

Who can perform this task: Platform Administrators

Prerequisites:

• The Artifactory Federation Service (RTFS) is installed and connected on the source and target JPDs
• Both JPDs are on supported versions with network reachability for API and binaries
• Admin permissions on the source and minimal required permissions on the target
• A trust or token option chosen. See Trust and Token Options.

Trust and Token Options

• Option A (recommended): Service Trust Pairing used to issue a receiving-only master token for enforcement. This is recommended when the target site must not be capable of pushing content to the source for governance or compliance reasons. Because the master token itself is receiving-only, it enforces restrictions across the entire site for the pairing. The target JPD's admin can't build federations that push content back to the source, and all federations built from source to target using this pairing are receiving-only on the target side.
• Option B: A regular master token with full permissions works functionally but doesn't enforce receiving-only posture at the trust boundary. This is typically used when you want the flexibility to establish both bidirectional and unidirectional federations between the same two JPDs, selecting unidirectional per repository (by setting the member mode to receiver). There's no site-level enforcement in this case. Enforcement relies entirely on the repository configuration.

This topic covers the following tasks:

• Create a New Federated Repository with Receiver Members
• Update an Existing Federated Repository to Receiver Mode
• Set Up Unidirectional Sync Using the REST API

Create a New Federated Repository with Receiver Members

For general repository creation steps not specific to receiver members, see Create a Federated Repository.

To create a Federated repository with receiving-only members:

1. In the Administration module, click Repositories > Create a Repository > Federated.

2. Fill in the Basic tab with the required fields (Repository Key, Package Type).

3. In the Federation tab, the current repository (local) is displayed.

4. Click Add Repository to add Federation members.

5. In the Add Federated Repositories dialog, enter the target member URL in the format: <PLATFORM_URL>/artifactory/<REPO_KEY>.

6. Click Done to add the member.

7. For each added member, a Receiving Only checkbox appears. Check this box to set the member to receiver mode (unidirectional sync).

   

8. Click Create Federated Repository to save the repository.

Update an Existing Federated Repository to Receiver Mode

To add or remove members from the Federation first, see Add and Remove Federation Members.

To set an existing Federation member to receiving-only mode:

1. In the Administration module, click Repositories.
2. Find and click on the Federated repository you want to modify.
3. Scroll to the Federation tab.
4. For each linked member (non-current repository), locate the Receiving Only checkbox:

   • Check the checkbox to set the member to receiver mode.

   • Uncheck to revert to bidirectional mode.

     

5. Click Save to apply changes.

Set Up Unidirectional Sync Using the REST API

Step 1: Establish Receiving-Only Trust with Service Trust Pairing

Skip to Step 2 only if you've chosen Option B (regular master token with full permissions). For governance and compliance use cases, complete this step using Option A.

1A. Generate a read-permission pairing token on the source JPD:

POST <JPD_URL>/artifactory/api/v1/service_trust/pairing/federated-repo/r
Authorization: Bearer <ADMIN_OR_SCOPED_TOKEN>

Response (example):

{ "pairing_token": "<PAIRING_TOKEN>", "expires_in": 300 }

1B. Exchange the pairing token on the target JPD to obtain a receiving-only master token:

PUT <JPD_URL>/artifactory/api/v1/service_trust/pairing/federated-repo/r
Authorization: Bearer <ADMIN_OR_SCOPED_TOKEN>
Content-Type: application/json

{ "pairing_token": "<PAIRING_TOKEN>" }

Where:

• <JPD_URL>: The base URL of the source or target JPD for the request
• <ADMIN_OR_SCOPED_TOKEN>: An admin or scoped access token for the JPD you're calling
• <PAIRING_TOKEN>: The short-lived pairing token generated in Step 1A

The target now holds a receiving-only master token suitable for creating receiver-restricted membership with the source.

Step 2: Create or Update the Federated Repository on the Source

2A. Create a federated repository with the target as receiver:

PUT <JPD_URL>/artifactory/api/repositories/<SOURCE_REPO_NAME>
Content-Type: application/json
Authorization: Bearer <ADMIN_OR_SCOPED_TOKEN>

{
  "rclass": "federated",
  "packageType": "generic",
  "members": [
    {
      "url": "<MEMBER_URL>/artifactory/<TARGET_REPO_NAME>",
      "mode": "receiver"
    }
  ]
}

For example:

{
  "rclass": "federated",
  "packageType": "generic",
  "members": [
    {
      "url": "https://target-jpd.example.com/artifactory/libs-release-federated",
      "mode": "receiver"
    }
  ]
}

2B. Update an existing federated repository to set receiver mode:

POST <JPD_URL>/artifactory/api/repositories/<SOURCE_REPO_NAME>
Content-Type: application/json
Authorization: Bearer <ADMIN_OR_SCOPED_TOKEN>

{
  "members": [
    {
      "url": "<MEMBER_URL>/artifactory/<TARGET_REPO_NAME>",
      "mode": "receiver"
    }
  ]
}

Where:

• <JPD_URL>: The base URL of the source JPD where you run the request
• <SOURCE_REPO_NAME>: The key of the Federated repository on the source JPD
• <ADMIN_OR_SCOPED_TOKEN>: An admin or scoped access token for the source JPD
• <MEMBER_URL>: The base URL of the target JPD
• <TARGET_REPO_NAME>: The key of the repository on the target JPD

Step 3: Initial Synchronization and Verification

3A. Automatic Full Sync on create/update: On repository create/update, Artifactory triggers a Full Sync automatically from the source to the target (receiver). No manual Full Sync call is required for initial synchronization. The reverse direction (target → source) is not possible in receiver mode.

3B. Validate health (required): This step confirms your Unidirectional Federation is fully operational. Don't consider setup complete until you verify these health checks pass.

Check repository connection state:

GET <JPD_URL>/artifactory/api/federation/status/connectionStates/<SOURCE_REPO_NAME>

Check JPD-wide federation summary on the Federation Dashboard or with the same API family:

GET <JPD_URL>/artifactory/api/federation/status/stateSummary

Where:

• <JPD_URL>: The base URL of the JPD you're checking
• <SOURCE_REPO_NAME>: The key of the Federated repository to check

Expected results:

If any checks fail, see Receiving-Only Troubleshooting.

Read-Only Behavior on Receiving-Only Members

When a Federation member is configured as receiving-only on a JPD, the federated repository on that JPD operates as a read-only repository. Receiving-only mode blocks outbound federation events and also blocks write operations that modify repository contents on that member.

The following operations are blocked when the local member is in receiver mode:

• Direct artifact upload (deploy)
• Direct artifact deletion
• Copy to the receiving-only federated repository
• Move from the receiving-only federated repository

Copy from a receiving-only federated repository is allowed. You can copy artifacts to a local repository or a bidirectional federated repository. Move from a receiving-only federated repository is blocked because a move deletes the source artifact. Deleting from a receiving-only member can break federation synchronization, and the artifact may be restored on the next Full Sync.

Attempts to perform blocked operations return an error similar to:

Direct upload on federated repository '<REPO_KEY>' is blocked: local member is in receiver mode
Direct delete on federated repository '<REPO_KEY>' is blocked: local member is in receiver mode
Direct copy/move on federated repository '<REPO_KEY>' is blocked: local member is in receiver mode

This behavior applies on the JPD where the member is configured as receiving-only. In a hub-and-spoke topology, receiving-only members on spoke JPDs can't accept local changes even when other members in the same federation use bidirectional mode. Promotion workflows and other write actions that target a receiving-only federated repository on that JPD fail.

Docker and OCI Repositories on Receiving-Only Members

When a Docker or OCI tag is overwritten (for example, when latest is re-pushed on the hub and replicated to a spoke), Artifactory schedules an automatic orphan-layer cleanup job on each member where the manifest changes. Orphan layers are blobs that belonged to a previous manifest and are no longer referenced by the current tag.

On receiving-only members, direct blob deletion is blocked, so the orphan-layer cleanup job can't remove unreferenced layers locally on that JPD. This is expected: receiving-only members accept content changes only through federation, including deletions initiated on bidirectional members.

Where cleanup runs in a hub-and-spoke topology:

Plan write operations and tag overwrites on the bidirectional (sender) member. Receiving-only spokes consume the replicated result.

Expected log messages: On busy Docker or OCI federated repositories in receiving-only mode, the automatic orphan-layer cleanup job may attempt local blob deletes that receiving-only mode blocks. The log format depends on your Artifactory version:

• Before the RTFS-3995 fix (current behavior on most deployments): ERROR - Failed in beforeDelete due to exception with Direct delete on federated repository '<REPO_KEY>' is blocked: local member is in receiver mode
• After the RTFS-3995 fix ships: WARN - Delete not allowed: Direct delete on federated repository '<REPO_KEY>' is blocked: local member is in receiver mode

Key points about these log entries:

• The delete is still blocked in both cases — only the log severity changes from ERROR to WARN.
• The cleanup job continues to retry until entries age out of its queue (default quiet period: 120 minutes, retry interval: 90 seconds).
• Entries typically appear with activity group DOCKER_TAG_ORPHAN_LAYER_CLEANUP or in federation mirror sync logs (Error while handling mirror sync response).
• They reflect read-only enforcement working as designed, not a permission misconfiguration or a broken federation pairing.

A follow-up platform update is planned to skip orphan-layer cleanup scheduling on receiving-only members entirely. Until then, treat these messages as informational when federation health checks pass, and monitor storage on spoke JPDs that receive frequent Docker or OCI tag overwrites since orphan layers persist temporarily until cleanup deletions replicate from the sender.

For more information about Docker orphan-layer cleanup, see Deletion and Cleanup of Docker Tags and Repositories.

Frequently Asked Questions

This section provides answers to frequently asked questions.

Related Topics

• Mirror Modes
• Create a Federated Repository
• Troubleshooting Federated Repositories
• Federation Dashboard
• Set Federation Priority