Using the latest JFrog products?
JFrog Platform User Guide

Skip to end of metadata
Go to start of metadata


To set up your initial Xray configuration, you can start with an optional preliminary phase in which you harden security for secrets on supported versions and platforms, and then we recommend going through the Onboarding Wizard which will be invoked automatically first time you run Xray. 

Once you have completed the Onboarding Wizard you may go through the following steps as needed at any time to update and add to your configuration.

  1. Connect to additional Artifactory instances and specify repositories that should be analyzed

  2. Manage Users

  3. Configure a mail server

  4. Configure webhooks

  5. Define Policies

  6. Define Watches

  7. Indexing artifacts 

  8. Synchronizing the database  

Xray Configuration File

Xray's configuration parameters are stored in its configuration file which is located at ${XRAY_DATA}/config/xray_config.yaml

Xray Installation Files

Xray's installation files will be placed at  ${XRAY_HOME} (/opt/jfrog/xray) for all Linux flavours.

When using Docker installation,  ${HOME}/.xray is used instead.

Connecting to Artifactory

You may connect Xray to several instances of JFrog Artifactory. When a connection between Xray and Artifactory is established, a user with "admin" privileges called xray is automatically created in Artifactory which allows Xray to access the data it needs to perform its different analyses and functions.

Before starting this process, make sure you do not already have a user called xray.

To view the list of Artifactory instances connected, in the Admin module, select Artifactory.

Connected Artifactory Services

Page Contents

The screen displays the list of Artifactory instances you have added to Xray showing:

The Artifactory ID you provided when registering the instance.
Artifactory URL
The URL of the registered Artifactory instance, including the "/artifactory" path (as in the screenshot).
Indicates if the Xray license in the selected Artifactory instance is valid or not.
Number of Indexed Files
Indicates the number of files has indexed for the Artifactory instance according to the repositories specified for analysis in Artifactory

Adding a New Instance

To add a new instance, click the New instance link and fill in the form displayed.

Artifactory ID
A logical identifier for this Artifactory instance.
A description of this instance.
Artifactory URL
The URL by which this instance will be accessed.
Proxy Enabled
When set, Xray will connect to this Artifactory instance through the HTTP proxy defined in the Admin module.
Admin User
A user with admin privileges in this instance.
Admin Password
The admin password.
Test Connection
Tests the connection between Xray and Artifactory (in both directions) to ensure you have configured it correctly.

Specifying Repositories for Analysis

To avoid a lengthy and intensive analysis processes, Xray does not analyze all repositories in the connected Artifactory instance. Instead, after you create a new Artifactory instance, Xray will display the repositories in that instance so you can select which ones should be indexed for analysis.

Selecting repositories for indexing

Once you have specified repositories for analysis in Artifactory, they will appear in the Repositories tab under Indexed Resources in the Artifactory Instance page (in the Admin module under Artifactory).

Indexed Repositories

You may now index artifacts in the selected repositories for analysis as described in Indexing Artifacts.

Specifying Builds for Analysis

To avoid a lengthy and intensive analysis processes, Xray does not analyze all builds in the connected Artifactory instance. Instead, after you create a new Artifactory instance, in the Builds tab of the Indexed Resources panel, you can select which builds should be indexed for analysis. 

Configure Indexed Builds

Want all builds scanned?

If you do want Xray to scan all builds, in the $XRAY_HOME/config/xray_config.yaml, set indexAllBuilds: true and restart Xray.

Managing Users

Xray supports two ways to manage users:

  1. Through an Authentication Provider
  2. Defining Users Internally

Managing Users Through an Authentication Provider

From version 1.9, you can set one of the connected Artifactory instances as an Authentication Provider. In this case, Artifactory will first try to authenticate users through the means set for that instance (whether LDAP/Crowd or SAML).

For details, please refer to Authentication.

Managing Users Internally

Using an Authentication Provider is not mandatory, and you can always define users internally within Xray.

You can view the list of users registered with Xray under the Admin module under Users


User Name
The user name with which the user should log on to Xray
The user's email. This is the default email to which notifications will be sent for this user's watchers.
Indicates if this user has admin privileges

Creating and Editing a User

To add a new user, click New user, or click an existing user in the table displayed to edit their details.

Creating and Editing a User

User Name
The user name that this user should log in with, or use to run REST API calls
The user's email
When set, this user will have admin privileges and therefore have access to a wider range of features and REST API calls

The user's password. The user will need this to log in or run REST API calls.

Configuring a Mail Server

Xray sends email notifications to users for different events that occur.

SaaS users

This configuration is not available for SaaS users where a default mail server is automatically configured.

Some examples are:

  • Watchers can send alerts by email.   
  • Users may be notified about changes in their account information

To enable mail notifications, you need to configure Xray with your mail server details under Admin | Mail as described below.

Mail Configuration

The host name of the mail server.
The port of the mail server.
The username for authentication with the mail server.
The password for authentication with the mail server.
From (optional)

The "from" address header to use in all outgoing mails.

Subject Prefix
A prefix to use for the subject of all outgoing mails.
Artifactory URL (optional)

The Artifactory URL to use in all outgoing mails to denote links to Artifactory.


When set, uses Transport Layer Security when connecting to the mail server.

Send Test Mail
Click to send a test message to the specified email address.

Configuring Webhooks

One of the options when configuring Watches is to have them invoke webhooks which are proprietary URLs you can define to perform custom actions as a result of a violation being issued.

Webhooks are displayed in the Admin module under Webhooks.


Click on a webhook to edit its details, or on New Webhook to define a new one.

New webhook

Webhook Name
An identifier for the webhook. This is the name that will be used by any Watches that want to invoke the webhook in case of a violation
The URL that this webhook invokes. For details of the payload provided by Xray to the webhook, please refer to Webhook Payload.
A free text description

Basic Auth
User Name/Password
A username and password as required by the webhook

Custom Headers
Any custom headers that may need to be added to invoke the webhook

Indexing Artifacts

JFrog Xray provides information on issues and vulnerabilities in components it has indexed.  During normal operation, the database of components is continuously updated and reindexed when changes are made to components in repositories marked for analysis, however, to set up the initial database you need to manually invoke indexing for the repositories that were marked for analysis.

In the Admin module, under Artifactory, you can view the list of connected Artifactory instances. Click the instance whose repositories you want to index. The details page for that instance shows the list of repositories marked for indexing.

Indexed repositories

This Index Status column will indicate for which repositories indexing is up-to-date, and which need to be indexed. You may click Calculate to initiate indexing of a single repository, or check several repositories and click Index Now to initiate indexing for multiple repositories at a time.

Resource intensive

Depending on the size of the repository, indexing be a resource intensive operation, so we recommend invoking indexing on repositories separately to avoid excessive loads on your system. 

Synchronizing the Database

Using a firewall?

If you are using a firewall, to allow the database sync to complete successfully, you need to add the following URLs to your firewall's whitelist:

To test the ability to sync, run the following REST API endpoint:

For Xray to scan your indexed artifacts it must ingest data on issues and vulnerabilities from the various feeds it is connected to. The primary feed comes from the global database server maintained by JFrog (additional feeds include direct connections you may have through Xray's integrations with external providers). There are two ways to synchronize Xray with the global database server:

  • Online: In online mode, Xray synchronizes with the global database server automatically on a daily basis through an internet connection
  • Offline: In offline mode, you manually download files from the global database server and then upload them to Xray 

To configure synchronization with the global database server, in the Admin module, select Database Sync

Online Synchronization

To get started right away so Xray can scan your artifacts, you may invoke the initial synchronization manually by selecting Start Sync in the Status panel. From then on, Xray will synchronize issues and vulnerabilities regularly and automatically, once a day.

Database Sync

Offline Synchronization

If, for any reason, you do not want to maintain a live internet connection to the global database server, select Offline in the Sync Mode panel to get detailed instructions on how to get the latest data available.

Version compatibility with JFrog CLI

 An offline database synchronization requires the use of JFrog CLI.

From Xray version 2.1.2, to do an offline synchronization, you must have JFrog CLI version 1.16.2 or higher.

Offline Synch

Pausing and Resuming Synchronization

Updating Xray with the latest data from the global database server may be a resource intensive operation. During an update, you may click the corresponding link in the Status panel to pause the operation at any time to free up resources, and then resume it later.

Working with SSL Using Self-Signed Certificates

Xray is able to work over a secure connection when connecting to other applications and services. For example, it connects to Artifactory through HTTPS. As part of the HTTPS protocol, Xray is able to verify the site's identity by validating its SSL certificate, however, in cases of a trusted connection, a site may use a self-signed certificate which cannot be validated (which may be the case in an Artifactory/Xray connection).

From version 2.0, the sslInsecure parameter was removed from the xray_config.yaml file. This configuration has moved to the General Settings in the Xray UI.

Configuring HTTPS Settings

You can configure access to Xray via HTTP, HTTPS or both (at least one is required).

To configure access to Xray with HTTPS, paste your SSL key and SSL certification files in the following directory: $XRAY_HOME/data/ssl/serverCerts

Then go to Admin module > HTTP Settings, click Refresh to see the added SSL files, and click save.

When set, Xray will be accessible via HTTPS at the corresponding port that is set.
Sets the port for the HTTPS server. The default value is 8000 and is configured in the xray_config.yaml file.
SSL Key Path
The full path to the key file for access via HTTPS.
(Note: this can only be configured by inserting your certificates in the $XRAY_HOME/data/ssl/serverCerts folder. See instructions above)
SSL Certificate Path
The full path to the certificate file for access via HTTPS. (Supported formats: .cer, .crt, .csr, .pem)
(Note: this can only be configured by inserting your certificates in the $XRAY_HOME/data/ssl/serverCerts folder. See instructions above)

For a Docker-based installation, copy the certificates to your xray-server container using the following command:

docker cp <PATH_TO_CERTIFICATES> <XRAY_SERVER_CONTAINER>:/var/opt/jfrog/xray/data/ssl/serverCerts

In case self signed certificates are used, enable ‘SSL Insecure’ in the Admin module, under General Settings. Then, import the certificates to Artifactory.

After setting up the certificates, update the ‘Xray Base URL’ to HTTPS and restart Xray.

When changing the default port to use a port below 1024, for example, to run a server listening on port 80, use the following command:

setcap cap_net_bind_service=ep /opt/jfrog/xray/bin/server

For Docker installations, exec into the xray-server container as root and run the following command:

setcap cap_net_bind_service=ep /opt/jfrog/xray-server/server


Configuring a Proxy

Depending on your organization's policies, you may need to configure Xray to access external resources through a proxy which may be configured in the Admin module under Proxy.

Configuring a Proxy

General Settings

Xray is built on a set of microservices that perform its actions in the realm of indexing artifacts, communicating with Artifactory, managing events and notifications and so on.

Basic Configuration

Xray Base URL

The base URL through which Xray can be accessed. The base URL uses the following format: PROTOCOL://IP_OR_HOST:8000

For example, or http://XRAY_HOST:8000

Note that the Xray Base URL should not be defined as "localhost", or "", and should not include the "/web" element. For example, the following base URLs would NOT work:,

Xray access URL is not its base URL

Be careful not to confuse Xray's access URL with its base URL.

Xray's access URL is: <XRAY_BASE_URL>/web/#/home

If you set the access URL in the Xray Base URL field, connected Artifactory instances will not be able to communicate with Xray

Queue Workers

Queue Workers offers several parameters you may configure to tweak the performance of Xray by changing the number of workers performing the different tasks.

The number of workers managing indexing of artifacts.
Binary Manager
The number of workers managing communication with Artifactory.
The number of workers handling events issued by Artifactory to Xray.
The number of workers managing persistent storage needed to build the artifact relationship graph.
The number of workers managing alerts.
The number of workers involved in scanning analysis.
Impact Analysis
The number of workers involved in impact analysis to determine how a component with a reported issue impacts others in the system.
The number of workers managing notifications.

System Parameters

SSL Insecure
Toggles enablement of skipping Xray's self-signed certificate validation
Mail Without SSL
Toggles usage of Transport Layer Security when connecting to the mail server
Max Disk Usage
Percentage of disk usage tolerated by Xray. When reaching the specified value, Xray will NOT download packages for indexing
Monitor Sampling Interval
Interval for executing monitoring jobs on CPU, Disk Usage, restarts, etc.
Queue Message Max TTL
Number of retries to be accepted in the Message Queue system
Job Interval
Interval for running node specific jobs

For more details on how adjusting these parameters may affect your system's performance, please contact JFrog Support.

Changing Third Party Service Credentials

Xray works with a number of third party services, such as various databases, which come pre-configured with default credentials for access by Xray. The following sections show how to change these default credentials.


To change the default credentials used by Xray to access its internal MongoDB database, you need to log into the database as the "xray" user, with the password that was established at the time Xray was installed. 

If the version of Xray that was initially installed was release 2.8.8 or older, the default password is "password". 

If the version of Xray initially installed was release 2.8.9 or newer, the default password is a random string that was generated by the install procedure, then encrypted by the Xray master.key. The generated password is stored under the /root folder as a text file called MongoDB_Admin_pass.txt. Depending on how Xray was installed, it might be in the local user's home directory: ~/MongoDB_Admin_pass.txt

You can log into the MongoDB database and change the password as follows:

# Access MongoDB as the Xray user
$ mongo --port 27017 -u "xray" -p "<current_password>" --authenticationDatabase "xray"
# Switch to the xray database
$ use xray
# Update the credentials
$ db.updateUser("xray",{pwd: "<new_password>"})
# Verify the update was successful by logging in with the new credentials
$ mongo --port 27017 -u "xray" -p "<new_password>" --authenticationDatabase "xray"


To change the default credentials used by Xray to access its internal PostgreSQL database, you need to log into the database as the "xray" user and change the password as follows:

# Access PostgreSQL as the Xray user adding the optional -W flag to invoke the password prompt
$ psql -d xraydb -U xray -W
# Securely change the password for user "xray". Enter and then retype the password at the prompt.
\password xray
# Verify the update was successful by logging in with the new credentials
$ psql -d xraydb -U xray -W


Xray comes pre-installed with RabbitMQ using its default credentials of: User:  guest, Password: guest

To change the default credentials, follow the steps below:

# Change the default password
$ rabbitmqctl change_password guest <new_password>
# Verify the update was successful
$ rabbitmqctl authenticate_user guest <new_password>

Hardening Security for Secrets

Xray uses a set of encrypted parameters (secrets) used to connect to external resources such as the different databases it uses. While these secrets may be stored in the Xray configuration file, this poses a risk of their being exposed.

To keep secrets safe from exposure, from version 2.5, on Xray installations running in Kubernetes, you may pre-load secrets from a temporary file first time you startup Xray. Once Xray has read and successfully used the secrets, the file is deleted.

The snippet below shows an example of the parameters you could include in this temporary file. These are the connection strings with which Xray connects to the different databases it uses.

	mqBaseUrl:            amqp://<user>:<password>@rabbitmq:5672/
    mongoUrl:             mongodb://<user>:<password>@mongodb:27017/?authSource=xray&authMechanism=SCRAM-SHA-1
    postgresqlUrl:        postgres://<user>:<password>@postgres:5432/xraydb?sslmode=disable

While we recommend only including sensitive information such as encrypted connection strings, this file may contain any of the Xray configuration parameters, and any parameters specified (including environment variables and system properties) will override the corresponding ones in the Xray configuration file.

  1. Once file is ready, create a Kubernetes secret from it. For example:

    kubectl create secret generic <SECRET_NAME> --from-file=<PATH/TO/TEMP/YAML>/temp.xray_config.yml
  2. Using an init container, pre-load the secret as a volume to each of your Xray services to a temporary path. 
    You also need to mount xray data-volume to /var/opt/jfrog/xray/data

  3. In the init container, copy temporary file to /var/opt/jfrog/xray/data/.secrets/.temp.xray_config.yml

  4. Start Xray. During startup, if the temporary configuration file exists, Xray will read all parameters from it, and then delete the file. If Xray fails to delete the file, Xray will not start and will issue an error.

A full pod restart is required

Since the temporary file is deleted when Xray starts, a full pod restart is required if the Xray service container crashes and restarts.

This is a known limitation of the pod lifecycle. The automated pod restart on container crash is currently not supported.

Watch the Screencast

Watch this screencast and learn how to troubleshoot your Xray installation for problems related to proxy connections, database, network and compute resources.

Configuring  PostgreSQL Connection Pools

You can configure the following PostgreSQL parameters in the xray_config.yml file for heightened system performance. 

maxOpenConnServer: 30
maxIdleConnServer: 15
maxOpenConnPersist: 30
maxIdleConnPersist: 15
maxOpenConnAnalysis: 30
maxIdleConnAnalysis: 15
maxOpenConnIndexer: 30
maxIdleConnIndexer: 15

  • No labels