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 in Docker containers. To make installation 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.

System Requirements

Hardware

JFrog Xray requires the following hardware:

  • Processor: 8 cores
  • RAM Memory: 16 GB
  • Storage: 100 GB

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 

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
rabbitmq hard nofile 100000
rabbitmq 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.

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.

 

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)
  • Npm
  • NuGet
  • Debian
  • RPM
  • Python (PyPI)
  • Docker
  • YUM

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 and start Xray, run the following commands:

    ./xray install
    ./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

Using RPM?

For an RPM installation, please ensure the following conditions hold:

  • JFrog Xray must be installed on a different machine from JFrog Artifactory.
  • The SELinux policy must either be permissive or disabled
  • 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
/var/opt/jfrog/xray/data/
Log files
/var/opt/jfrog/xray/data/logs
Log configuration files
/var/opt/jfrog/xray/data/config

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

    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 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

 

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

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.

Registering a 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