v2utils

README

V2utils (Xray utility)
======================

This project provides a simple command-line tool, that extends
the xray-core program <https://github.com/xtls/xray-core>.


Quick introduction
------------------

Many web interfaces (v2ray panels) are available and used for
managing and configuring V2ray/Xray servers. These interfaces
usually create a URL to configure the client-side programs.

Although these URLs (e.g. vless://uuid@ip:port) are commonly
used, they are not supported by traditional command-line
Xray and V2ray programs; only mobile and GUI applications
like v2rayNG on Android, and v2rayN support them.

This project extends the xray-core command-line program
by adding functionalities to use (run), test and convert
json configs and proxy URLs directly.

Build / Install
---------------

* To build from source:
  Simply run `make` at the root of the project.
  Use `make debug` to build with logs in debug mode.

* To Install via go command:
  `go install -v github.com/siamak-amo/v2utils/cmd/v2utils@latest`


Usage examples
==============

V2utils supports three commands: Convert, Test and Run.
Run v2utils with command `v2utils COMMAND` or create soft links
for each command separately:  v2convert, v2test, and v2run.

As a common convention, all commands:
 - Use stdin if a dash is passed as argument to --config, --url.
 - Use stdin if no --url option is provided.
 - Use stdout if no --output option is provided.
 - Read all json files from a directory, if the --config option
   points to a directory rather than an explicit file path.
 - Use the default template if no --template is provided


Convert command
---------------

The Convert command, maps proxy URLs to the 'outbounds' section
of the json template given by the --template option.
It can also convert 'outbounds' section of the json files,
back into their compatible URL.

* Converting proxy URLs to json
  $ v2utils convert --output /path/to/destination_dir \
                       --url 'vless://id@1.2.3.4:1234/?type=tcp' \
                  --template template.json

  Where the template.json file would look like:
  {
      "log": {"loglevel": "error"},
      "inbounds": [
          {"listen": "127.0.0.1", "port": 8080, "protocol": "http"}
      ],
      "routing": {}
  }

* Converting 'outbounds' of json files to URL:
  $ v2utils convert --config /path/to/conf_dir


Test command
------------

The Test command determines broken and functional configurations
by verifying the accessibility of some well-known endpoints through
the VPN client with the current configuration.

* Test URLs and collect only functional ones:
  $ cat urls.txt  |  v2utils test  >  urls.working.txt

* Test and create equivalent json file for functional URLs:
  $ cat urls.txt  |  v2utils test --output /path/to/dst_dir

* Test json files:
  $ v2utils test --config /path/to/config_dir
  To also delete broken files, pass --rm

* Test json files and rename broken files to .old
  $ v2utils test --reverse  2>/dev/null \
                 --config /path/to/config_dir | \
      while read file; do mv $file $file.old; done

  By default, v2utils uses stdout to print functional configs,
  while using the reverse option, it only prints broken
  files and URLs on stdout.


Run command
-----------

The Run command executes an Xray instance using the provided
URL and template  or  with config file.

* Run with URL:
  To run with a URL, use the --url option for 'outbounds', along
  with a template.json file for 'inbounds', 'routing', 'logs', etc.

  $ v2utils run --url 'vless://id@1.2.3.4:1234' \
           --template template.json


Source code
===========

 - cmd: Dedicated to the command-line interface.
 - internal: Contains low-level functions for converting URL <-> JSON.
 - pkg: It provides running, testing and converting functionalities.
        It is reusable as a library (interface to internal).