Have a question? Want to report an issue? Contact JFrog support

Skip to end of metadata
Go to start of metadata

Overview

JFrog Xray is a complementary product to JFrog Artifactory and is run as a separate installation as a set of microservices. 

Both Docker and Non-Docker installation flavours are as quick and easy as possible, you only need to download a simple script that manages download and installation of all the other components needed to run Xray.

To get started, make sure your system complies with the requirements in the following section before you proceed to download and install Xray.

Installer Log

As part of the installation/upgrade Xray creates a log file to track the installation process. Each installation/upgrade will create a new install log file with the following format:

${INSTALLER_DIR}/${SCRIPT_NAME}.${DATE}.log

Xray High Availability

 If you are installing an Xray HA cluster, please refer to HA Installation and Setup.

Using non-interactive automated scripts to install Xray

To install/upgrade Xray using automation, add the following to your environment variables and the xray-env.conf file:

USE_DEFAULTS=true

Existing parameters will be used in the automation process.

System Requirements

Hardware

JFrog Xray requires the following hardware:

  • Processor: 8 cores
  • RAM Memory: 16 GB
  • Storage: 100 GB
  • A separate host machine (Xray should not run on the same machine as Artifactory)   

Minimum requirements

Note that these are minimum requirements for Xray to run. When Xray is used more intensively such as in larger installations or for scanning Docker images, RPM packages etc., you may need to provide more hardware resources.

Allocated storage space may vary

Xray downloads and then deletes fetched artifacts after indexing. However, in order to have more parallel indexing processes, and thereby more temporary files at the same time would require more space.

This is especially applicable for large BLOBs such as Docker images.

Platforms

JFrog Xray supports any non-Windows platform that can run Docker v1.11 and above, and in addition, has been tested and verified to run as a non-Docker installation on the following 64-bit flavors of Linux:

  • Ubuntu 14.04 
  • Centos 7.x
  • Debian 8.x
  • Red Hat 6.x 
  • Red Hat 7.x 

OS Libraries

Make sure your OS libraries are up-to-date

Page Contents

File Handle Allocation Limit

Avoid performance bottlenecks

In the process of deep recursive scan in which Xray indexes artifacts and their dependencies (metadata), Xray needs to concurrently manage many open files. The default maximum number of files that can be opened concurrently on Linux systems is usually too low for the indexing process and can therefore cause a performance bottleneck. For optimal performance, we recommend increasing the number of files that can be opened concurrently to 100,000 (or the maximum your system can handle) by following the steps below.

Use the following command to determine the current file handle allocation limit:

cat /proc/sys/fs/file-max

Then, set the following parameters in your /etc/security/limits.conf file to the lower of 100,000 or the file handle allocation limit determined above.

The example shows how the relevant parameters in the /etc/security/limits.conf file are set to 100000. The actual setting for your installation may be different depending file handle allocation limit in your system.

root hard nofile 100000
root soft nofile 100000
xray hard nofile 100000
xray soft nofile 100000
postgres hard nofile 100000
postgres soft nofile 100000
mongodb hard nofile 100000
mongodb soft nofile 100000
Screencast

Docker

JFrog Xray requires Docker v 1.11 and up to be installed on the machine on which you want to run Xray. For instructions on installing Docker, please refer to the  Docker documentation.

Browsers

Xray has been tested with the latest versions (known at the time of release) of Google Chrome, Firefox, Internet Explorer, Microsoft Edge and Safari.

Archiving and Compression

Xray has been tested with the following archiving types (known at the time of release) of Tar (Bz2, Gz, Z, infl, Xp3, xz), Zip , rpm, deb, and 7zip.

Artifactory

From version 1.1, JFrog Xray supports JFrog Artifactory v4.0 and above.

Older versions of JFrog Xray only support JFrog Artifactory v4.11 and above.

Recommended Artifactory Version

We recommend using JFrog Xray with JFrog Artifactory v4.12 and above for best integration and performance experience.

JFrog Xray 1.12 was co-released with Artifactory 5.10. Due to a fundamental change in the integration of Xray with Artifactory in these versions, the following matrix describes version compatibility going forward:

 Xray Version
1.12+<1.12

 

Artifactory
Version

5.10+

(tick)

Since both Artifactory and Xray are upgraded, the new integration is fully functional as designed.

(error)

In this combination, the integration will not work since the new version of Artifactory will query Xray for scan status, however, the old version of Xray does not have the required REST API endpoints.

<5.10

(warning) 

This combination is supported. Artifactory will continue to display each artifact's scan status, however, it will use previous mechanism that uses properties.

(tick)

If neither Artifactory nor Xray are upgraded, the integration will work using the previous mechanism that displayed scan status as a set of properties on the artifact.

Feature Compatibility

Artifactory and Xray progress independently, and some features in Xray require specific versions in Artifactory for support as described in the following table:

FeatureArtifactory VersionXray Version
CI/CD Integration

v >= 4.16

v >=1.6
Bi-directional connection testv >= 4.15v >=1.3
Xray license validationv >= 4.11v >=1.0
Download blocking based on Xray alertsv >= 4.13v >=1.1
Xray section in General Information tab of selected artifact in Artifactory's tree browserv >= 4.11v >=1.0
Synchronizing artifacts via REST APIv >= 4.11v >=1.0
Synchronizing artifacts through a user plugin4.11 > v >=4.0v>=1.1

Supported Technologies

JFrog Xray supports scanning and impact analysis for the following package formats:

  • Java (Maven, Gradle, Ivy, SBT)
  • JavaScript (NPM)
  • .NET (Nuget)
  • Python (PyPi)
  • Docker
  • Debian
  • RPM
  • Ruby Gems
  • Python Wheels

Download and Installation

JFrog Xray may be installed as a Docker image, or as a non-Docker installation for each of the supported flavors of Linux. Once you have downloaded your preferred installer, follow the installation instructions in the corresponding sections below.

The  Xray Download Page provides the JFrog Xray installer for any of the supported platforms (Docker or Linux flavors).

Keep Xray on your $PATH

Make sure to save the downloaded file in one of the locations defined in your $PATH environment variable so it is accessible from anywhere on your machine.

Docker Installation

Running Xray without Docker

To run Xray as a non-Docker installation, please refer to Linux Installations

The JFrog Xray Docker image may be installed on  any platform supporting Docker v1.11 and above. To install Xray as a Docker image, make sure you have an network connection and follow the instructions below:

  1. Make xray executable
    To give xray execute privileges on your machine, run: 

    chmod +x xray
  2. Install and start Xray
    The installation process will prompt you for a "root folder". You may keep the defaut (current) location or specify another location on your machine. Choose this location carefully since you may not change it later, and this is where JFrog Xray saves its data, configuration files and logs. The Xray installer will only prompt you for this location for initial installation. It is stored for later use when upgrading.


    To install Xray, run the following command:

    sudo ./xray install

    Using External Databases

    JFrog Xray uses several databases for different features of its operation. Until version 1.10, Xray installed an instance of all of these databases dedicated for its own use.

    From version 1.10, Xray gives you the option of using your own MongoDB and Postgres databases if you have these already installed and in use in your organization.

    For more details, please refer to Using External Databases.


    To start Xray, run the following command:

    ./xray start



Port Configuration

 Make sure ports on your JFrog Xray and JFrog Artifactory installations are properly configured to enable communication between the two applications.

Upgrading on Docker

For instructions on how to upgrade an existing installation, please refer to Upgrading Xray

Interacting with the Docker Installer

In addition to managing installation, the xray installation script can provide additional information or perform additional tasks on your installation such as restarting Xray, displaying log files and more. For details, run:

./xray help

Linux Installation

Installation requirements

Please ensure the following conditions hold:

  • JFrog Xray must be installed on a different machine from JFrog Artifactory.
  • The umask (user file creation mode mask) must have a default setting of 0022, 022, 0002 or 002

Using a third-party log collector

To use an external log collector that requires a separate user for Xray (e.g. Sumologic, Splunk) , you can adjust the permissions on the $XRAY_HOME/data/logs folder to allow the the log collection service to perform read operations on the generated log files as follows:

  1. Add the log collection service user to the relevant group if needed (the user and group that installed and started Xray)
  2. Apply the user and group permissions as needed on the $XRAY_HOME/data/logs directory using:

    $ chmod -R 640 $XRAY_HOME/data/logs 
  3. Adjust the group read inheritance permissions setgid bit using:

    $ chmod -R 2755 $XRAY_HOME/data/logs 


    This will cause the generated log files to inherit the folder's group permissions.
     

The Xray Linux installation follows standard conventions and installs Xray in the following folders:

Application files
/opt/jfrog/xray
Data files

Default: /var/opt/jfrog/xray/data/

The installation script will prompt you for an optional alternative location.

Log files
/var/opt/jfrog/xray/data/logs
Log configuration files
/var/opt/jfrog/xray/data/config
PostgreSQL home directory

Default: /var/opt/jfrog/postgres

The installation script will prompt you for an optional alternative location.

Scripts directory

/opt/jfrog/xray/scripts

The xray.sh script include inside this folder.

In all of the instructions below, replace the <linux-flavor> place-holder with one of centosdebianubuntu or redhat according to the flavor of Linux on which you are operating.

The installation instructions for all of the supported flavors of Linux are the same.

  1. Extract the downloaded installation archive

    tar -xzf xray-<linux-flavor>-latest.tar.gz
  2. Run the installation script
    (if you are not running as "root", prepend the following command with "sudo")

    ./installXray-<linux-flavor>.sh

    Using External Databases

    JFrog Xray uses several databases for different features of its operation. Until version 1.10, Xray installed an instance of all of these databases dedicated for its own use.

    From version 1.10, Xray gives you the option of using your own MongoDB or Postgres databases if you have these already installed and in use in your organization.

    For more details, please refer to Using External Databases.

Upgrading on Linux

For instructions on how to upgrade an existing installation, please refer to Upgrading Xray

Interacting with the Linux Installer

Make sure Xray fully started

Verify all the required Xray components and connected databases are up and running by the following command:

./xray.sh status all
 

Use the below command to start all Xray components:

./xray.sh start all
 

It is also possible to exclude the 'all' flag which will make the script run or check only for the running Xray services (without the databases):

 

./xray.sh status
./xray.sh start 

 

The installation script offers facilities for maintenance. Run the following commands as "root" or prepend them with "sudo".

./xray.sh <command> <target (optional)>

where:

<command> can take one of the following values:

start
Start the service
stop
Stop the service
restart
Restart the service
status
Display the service status (e.g. running, stopped...)
info
 Displays version information for each service
deployServices
Deploy the service (only available for the xray service)
removeServices
Remove the service (only available for the xray service)

<target> Optional. When omitted, the command only applies to the Xray service.

 

all
Apply the command to all services

Using External Databases

JFrog Xray uses several databases for different features of its operation. Until version 1.10, Xray installed an instance of all of these databases dedicated for its own use.

From version 1.10, Xray gives you the option of using your own Postgres or MongoDB  databases if you have these already installed and in use in your organization.

Supported database versions

Currently, Xray supports the following external database versions:

PostgreSQL: version 9.5.2

MongoDB: version 3.2.6

While both of these databases are required, it is up to you to choose which, if any of them, to externalize when you install Xray. Xray will install these databases if you choose not to externalize them.

During the installation process, the Xray installation script will prompt you with questions about whether to install an internal database or to use one already installed in your organization. Simply respond to these prompts as required. Either way, once installation is completed, Xray needs to be linked to both databases to work.

You take full responsibility for your own databases

If you choose to have Xray use any of your own databases for its operation, you take full responsibility for the maintenance, backup and correct functioning of these databases.

For example, the Xray installation script will ask if you would like to install Postgres or MongoDB.

If you respond with a "Y", Xray will install Postgres or MongoDB for its own use.

Would you like to install PostgreSQL instance? [Y/n]: n
Type a PostgreSQL connection string [postgres://xray:xray@postgres:5432/xraydb?sslmode=disable]: postgres://xray:xray@<MACHINE_IP>:5432/xraydb?sslmode=disable
Would you like to install MongoDB instance? [Y/n]: n
Type a MongoDB connection string [mongodb://xray:password@mongodb:27017/?authSource=xray&authMechanism=SCRAM-SHA-1]: mongodb://xray:password@<MACHINE_IP>:27017/?authSource=xray&authMechanism=SCRAM-SHA-1

Accessing Xray

JFrog Xray can be accessed using the following URL:

http://<SERVER_NAME>:8000/web/#/home

For example, if you are accessing Xray on a machine called "myserver" you would use:  http://myserver:8000/web/#/home

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 of Xray's basic configuration, connected Artifactory instances will not be able to communicate with Xray

 


Activating Xray

Purchase - Automatic Activation

If you have purchased Xray, it is activated automatically when you connect it to a licensed Artifactory instance - one that has an Xray license incorporated into the Artifactory license.  

Purchased a license?

Make sure to activate your Artifactory instances with a comprehensive license that includes Xray activation.

If you are currently evaluating JFrog Xray (i.e. you are on a free trial), you need to set your license manually in order to activate it.

Free Trial - Manual Activation

If you have requested an evaluation of Xray, your license key will be provided to you as part of the registration process

Problems activating Xray?

If you have any problems receiving your license or activating Xray, please contact JFrog Support.

Your administrator should enter the license key manually into the corresponding field in the Admin module under Register License.

Register License


Default Admin User

Once installation is complete, Xray has a default user with admin privileges predefined in the system:

User: admin

Password: password

Change the admin password

We strongly recommend changing the admin password as soon as installation is complete.

  • No labels