Overview

The YAML configuration file offers an alternative way to specify your initial settings for JFrog Distribution. 

To get you up and running as quickly and easily as possible for a new installation, you can configure your basic initial setup through the filesystem, before starting Distribution for the first time.

Any edits will apply to the whole Distribution cluster.

Modifying the Distribution configurations is an advanced feature, and if done incorrectly may render the Distribution service in an undefined and unusable state. Since it is easy to overwrite configurations, we strongly recommend backing up the configuration before making any direct changes, and taking great care when doing so.

The default Distribution home directory is defined according to the installation type. For additional details see the System Directories page.

Note: This guide uses $JFROG_HOME to represent the JFrog root directory containing the deployed product.

Applying Configuration Changes

To update the application configuration using the yaml file, follow these steps:

  1. Copy the template yaml file.

    cd $JFROG_HOME/distribution/var/etc/distribution/
cp template.distribution.config.import.yml distribution.config.import.yml
  2. Edit the properties in the new distribution.config.import.yml file
  3. Restart the Distribution service with the updated yaml file. This update will propagate to the additional nodes.

A snapshot of the last imported configuration state will be saved as distribution.config.latest.yml.

Previous yaml configuration files will be saved as distribution.config.TIMESTAMP.yml. Up to a maximum of 10 previous configuration states.

Supported Configurations

##################################################################
# To edit the Distribution cluster configurations,               #
# edit this file and rename it to distribution.config.import.yml #
# then restart Distribution                                      #
##################################################################

schema-version: 1

task:
  heartbeat:
    interval-seconds: 5        # interval between successive runs of the heartbeat job
    consider-stale-seconds: 30 # the time period (seconds) a server can remain unresponsive before being considered stale in the cluster
  distribute:
    interval-seconds: 5        # interval between successive runs of the distribute job
  release-bundle-handler:
    interval-seconds: 5        # interval between successive runs of the release bundle handler job
  health-check:
    interval-secs: 15          # interval between successive runs of the health check job

probes:
  liveness:
    fail-on-long-failing-readiness:
      enabled: true
      failure-duration-secs: 60       # maximum failure time before starting liveness auto healing

cluster:
  sync:
    timeout-millis: 100               # initial time (ms) to wait before retrying a request
    socket-timeout-millis: 5000       # time to wait (ms) before giving up on executing a REST call on another server
    exponential-backoff-multiplier: 2 # number by which the retry timeout should be multiplied before a subsequent retry. For example, by default, the third retry will happen after 200 ms
    number-of-retries: 3              # maximum number of retries
    backoff-max-delay-millis: 1000    # maximum time between successive retries regardless of other settings

call-home:
  enabled: true

release-bundle:
  max-artifacts: 3000 # maximum number of artifacts to fetch from artifactory on release bundle creation

distribute:
  distribution-to-source-artifactory:
    use-user-permissions: true  # whether to use user token in distribution to source artifactory
  edge-node-token-expiration-minutes: 180 # the time period (minutes) a token lives for communicating with edge node
  load-balancer: "weight-based"           # algorithm to use for distributing the work between the Distribution nodes
  auto-create-target-repo-advance: false  # allow auto target repositories creation if complex mappings are set

server:
  max-http-header-size: 16384 # 16kb in bytes

frontend:
  serve-statics-from-distribution: true # whether the frontend static files should be served from the distribution server. NOTE: for this change to take place all distribution nodes in the cluster need to be restarted

access-client:
  client-connection-timeout: 60000    # connection timeout in millis for Access client requests. e.g.: token verification, authentication

artifactory-client:
  client-short-socket-timeout: 10000    # socket timeout in millis for Artifactory bound short tasks, e.g.: auth and pairing with Artifactory
  client-long-socket-timeout: 120000    # socket timeout in millis for Artifactory bound long tasks, e.g.: release-bundles' store, deletion and artifacts' gathering (AQL) queries

xray:
  release-bundle-scan-consider-stuck: 600000    # the time in millis for xray vulnerability scanning considering stuck
  allow-distribution-when-xray-is-unavailable: true   # allow distribution when xray is unavailable
  grace-period-for-xray-triggering-in-millis: 600000  # the time in milliseconds for retry xray vulnerability scanning triggering
 

token:
  distribution-token-cache-expiration-millis: 3540000   # the amount of millis for the distribution tokens cache to be expired
  master-token-cache-expiration-millis: 30240000000     # the amount of millis for the master tokens cache to be expired

system:
  service-info:
    service-info-cache-expiration-millis: 30000  # the amount of millis for the service info cache to be expired

The Request header max size can manually be increased to prevent receiving an HTTP 400 message when signing into Distribution with SSO.
For this change to take effect, each distribution node in the cluster must be restarted. Start with rebooting the first node one on which the config file is installed and proceed to the remaining Edge nodes.

Setting the User Scoped Token for Distribution to Source Artifactory

From Distribution 2.13.2, user permissions will be enforced when distributing to the source JPD. The permissions are as follows:

  • To distribute release bundles: Only users with read and deploy permissions on the target repositories can successfully complete a distribution process to the source Artifactory (in this case the JPD acts as the target JPD).

    If this type of user (non-admin) tries to distribute to a target repository that does not exist, they will receive an error message.

  •  To delete release bundles: Only users with delete permission for the target repository can delete these bundles.

distribute:
  distribution-to-source-artifactory:
    use-user-permissions: true  # whether to use user token in distribution to source artifactory

Once you upgrade your Distribution version to this release, the user scoped token becomes the default configuration for Distribution. 

This feature requires you to have Artifactory 7.40.x and later installed for the source Artifactory (not target). Otherwise, even if you have set this configuration to true, it will revert to the current setting.

This setting is relevant only for distributing to the source Artifactory.


Deploying Your GPG Key on the Source Artifactory

Distribution will trigger the source Artifactory to clone the contents of signed release bundles into an isolated release-bundles repository. To allow this, you need to deploy the GPG Key that is used in each of your Artifactory Edge nodes to the source Artifactory service.

For more details, refer to Setting a GPG Key.

For more details on additional required configurations, refer to configuring Distribution.