Using the latest JFrog products?
JFrog Platform User Guide
JFrog Xray 2.x Documentation
To get the latest version, go to the JFrog Unified Platform
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 mongod hard nofile 100000 mongod 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 | 5.10+ | Since both Artifactory and Xray are upgraded, the new integration is fully functional as designed. | 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 |
This combination is supported. Artifactory will continue to display each artifact's scan status, however, it will use previous mechanism that uses properties. | 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:
Feature | Artifactory Version | Xray Version |
---|---|---|
CI/CD Integration | v >= 4.16 | v >=1.6 |
Bi-directional connection test | v >= 4.15 | v >=1.3 |
Xray license validation | v >= 4.11 | v >=1.0 |
Download blocking based on Xray alerts | v >= 4.13 | v >=1.1 |
Xray section in General Information tab of selected artifact in Artifactory's tree browser | v >= 4.11 | v >=1.0 |
Synchronizing artifacts via REST API | v >= 4.11 | v >=1.0 |
Synchronizing artifacts through a user plugin | 4.11 > v >=4.0 | v>=1.1 |
Supported Technologies
JFrog Xray supports scanning and impact analysis for a variety of package formats, recursively scanning the layers of supported packages and their dependencies, and providing a component graph to display the impact of vulnerabilities and license compliance issues discovered. For a full list of supported package formats, please refer to Supported Technologies.
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:
Make
xray
executable
To give xray execute privileges on your machine, run:chmod +x xray
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 non-interactive automated scripts to install Xray
To install/upgrade JFrog Xray using unattended mode, set the following environment variable and the xray-env.conf
file:
export USE_DEFAULTS=true
The unattended installation configures JFrog Xray as a standalone instance includes these Xray microservices, common resources, and the default file system structure.
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
3. (Optional) Disable and replace the RabbitMQ 'Guest' User.
Disabling and Replacing the RabbitMQ 'Guest' User (Docker)
- Connect to the container and create a new 'Admin' user, run the following script.
docker exec -it <rabbitmq_container> bash rabbitmqctl add_user <user> <password> rabbitmqctl set_user_tags <user> administrator rabbitmqctl set_permissions -p / <user> "." "." ".*"
To delete the 'Guest' user, run the following script.
rabbitmqctl delete_user guest service rabbitmq-server restart
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:
- Add the log collection service user to the relevant group if needed (the user and group that installed and started Xray)
Apply the user and group permissions as needed on the
$XRAY_HOME/data/logs
directory using:$ chmod -R 640 $XRAY_HOME/data/logs
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 centos, debian, ubuntu 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.
Extract the downloaded installation archive
tar -xzf xray-<linux-flavor>-latest.tar.gz
Run the installation script
(if you are not running as "root", prepend the following command with "sudo")./installXray-<linux-flavor>.sh
Using non-interactive automated scripts to install Xray
To install/upgrade JFrog Xray using unattended mode, execute install script with the following parameter:
./installXray-<linux-flavor>.sh --use-defaults
Alternatively, export the following your environment variable:
export USE_DEFAULTS=true
The unattended installation configures JFrog Xray as a standalone instance includes these Xray microservices, common resources, and the default file system structure.
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.
3. (Optional) Disable and replace the RabbitMQ 'Guest" User.
Disabling and Replacing the RabbitMQ 'Guest' User (Linux)
Create a new 'Admin' user, by running the following script.
rabbitmqctl add_user <user> <password> rabbitmqctl set_user_tags <user> administrator rabbitmqctl set_permissions -p / <user> "." "." ".*"
Edit your $XRAY_HOME/data/config/xray_config.yaml file with the latest user and password for mqbase url.
mqBaseUrl: amqp://<new user>:<password>@rabbitmq:5672
- Restart all your Xray services.
Delete the default 'Guest' user, by running the following script.
rabbitmqctl delete_user guest service rabbitmq-server restart
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 |
Installing on Kubernetes
Xray Helm chart is available for installing JFrog Xray on Kubernetes using this Xray Helm Chart.
The sources for this chart are available in JFrog's charts GitHub repository.
Installation
Detailed instructions on installing and upgrading Xray are documented in the chart's README.md file which is available on JFrog's charts GitHub repository:
JFrog Xray Installation and Upgrade on Kubernetes.
Available on Helm Hub
The installation and upgrade instructions for Xray are also available on Helm Hub:
Common Resources
During the Xray Installation process, the following common resources are installed:
Resource | Description | Default Ports |
---|---|---|
Used to persist and navigate through the organization's components graph. This is either installed as part of the Xray installation or manually. | 5432 | |
Used to store components metadata and configuration. This is either installed as part of the Xray installation or manually. | 27017, 28017 | |
RabbitMQ | Used to handle all microservices communication and to ensure no data loss. By default, the RabbitMQ Management Console 'Guest' user is installed. You can disable the default user and create your own one using our Docker and Linux customized scripts. | 4369, 5671, 5672, 15672, 25672, 15671 |
Xray Services
Service | Description | Default Ports |
---|---|---|
Server | Responsibilities include:
| 8000 |
Analysis | Responsible for enriching component metadata such as vulnerabilities, licenses and versions. | 7000 |
Persist | Responsibilities include:
| 7003 |
Indexer | Responsible for the indexing process, including:
| 7002 |
Using External Databases
JFrog Xray uses several databases for different features of its operation including both PostgreSQL and MongoDB. 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 PostgreSQL and/or MongoDB databases if you have either or both of these already installed and in use in your organization.
Supported database versions
Currently, Xray supports the following external database versions:
PostgreSQL: version 9.5 and 9.6 (note that these versions will be EOL soon), 10.x, 11.x, 12.x (the earliest version of Xray 2.x that supports PostgreSQL 10-12 is Xray 2.16)
MongoDB: version 3.2.6 and 3.6.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 and MongoDB.
In each case, if you respond with a "Y", Xray will correspondingly install Postgres and 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
//Creating default admin user var adminUser = { user:"admin", pwd: "password", roles: ["root"], customData: { createdBy: "JFrog Xray installer" } } db.getSiblingDB("admin").createUser(adminUser) //Creating default xray user var xrayUser = { user:"xray", pwd: "password", roles: ["dbOwner"], customData: { createdBy: "JFrog Xray installer" } } //Authenticating as admin to create xray user var loginOutput = db.getSiblingDB("admin").auth(adminUser.user,adminUser.pwd) db.getSiblingDB("xray").createUser(xrayUser)
CREATE USER xray WITH PASSWORD 'xray'; CREATE DATABASE xraydb WITH OWNER=xray ENCODING='UTF8'; GRANT ALL PRIVILEGES ON DATABASE xraydb TO xray;
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.
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.