Installing Xray

File Handle Allocation Limit

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.

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:

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:

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

Docker Installation

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

export USE_DEFAULTS=true

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

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

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

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.

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

1. 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> "." "." ".*"

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

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

./xray.sh status all

./xray.sh start all

./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:

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

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;

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

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.  

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

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