# v2fly/fhs-install-v2ray

**Attribution required: if you use, quote, or summarise this content, you must credit and link back to [awesome-repositories.com](https://awesome-repositories.com/repository/v2fly-fhs-install-v2ray).**

6,756 stars · 1,483 forks · Shell · gpl-3.0

## Links

- GitHub: https://github.com/v2fly/fhs-install-v2ray
- awesome-repositories: https://awesome-repositories.com/repository/v2fly-fhs-install-v2ray.md

## Topics

`installer` `script` `v2ray`

## Description

fhs-install-v2ray is a shell script that automates the deployment of V2Ray, a network proxy tool, on Linux servers. It downloads precompiled binaries and geographic data from a release server, places them into standard Linux filesystem directories, and registers V2Ray as a persistent background service managed by systemd. The script is designed to be idempotent, meaning repeated runs do not overwrite custom configurations, and uninstallation removes all installed files and services completely.

The tool distinguishes itself by enforcing a Filesystem Hierarchy Standard (FHS) layout, mapping binaries to `/usr/bin`, data to `/usr/share`, and configuration to `/etc/v2ray` for consistent cross-distribution compatibility. It generates systemd unit files from a template during installation, enabling automatic startup, stop, and log management. The script also supports version-pinned asset fetching, allowing deterministic deployment by downloading release assets using a specific version tag from the upstream repository.

Beyond basic installation, the script can migrate existing V2Ray configuration files from old default directories to the new FHS-compliant location, skip geographic data updates to preserve custom rule sets, and symlink TLS certificates from Certbot for automatic renewal. It handles the full lifecycle of V2Ray deployment, including clean removal of all binaries, data, configuration, logs, and service files.

The installation script requires only standard POSIX tools like curl and tar, with no external dependencies beyond the shell itself.

## Tags

### Development Tools & Productivity

- [V2Ray Installers](https://awesome-repositories.com/f/development-tools-productivity/automated-installation-scripts/v2ray-installers.md) — Provides a shell script that automates the full lifecycle of V2Ray deployment on Linux servers.
- [FHS-Compliant Deployments](https://awesome-repositories.com/f/development-tools-productivity/build-tooling/build-orchestration-logic/build-orchestration-configuration/build-automation-systems/build-systems/binary-compilation-toolchains/server-binary-compilers/binary-distribution/fhs-compliant-deployments.md) — Maps binaries to /usr/bin, data to /usr/share, and config to /etc/v2ray for consistent cross-distribution layout.
- [Asset Bundling](https://awesome-repositories.com/f/development-tools-productivity/build-tooling/build-performance-optimization/build-optimization-tools/bundle-optimizers/asset-bundling.md) — Packages compiled binaries and geographic data into compressed archives for streamlined deployment.
- [FHS-Compliant Path Managers](https://awesome-repositories.com/f/development-tools-productivity/installation-path-managers/fhs-compliant-path-managers.md) — Enforces an FHS-compliant layout, placing binaries in /usr/bin and data in /usr/share for cross-distribution consistency. ([source](https://cdn.jsdelivr.net/gh/v2fly/fhs-install-v2ray@master/README.md))
- [Idempotent Installers](https://awesome-repositories.com/f/development-tools-productivity/installation-scripts/idempotent-installers.md) — Ensures repeated runs do not overwrite custom configs and uninstallation removes all files and services completely.

### Business & Productivity Software

- [Background Services](https://awesome-repositories.com/f/business-productivity-software/background-services.md) — Integrates with systemd to run V2Ray as a persistent background service with automatic lifecycle control. ([source](https://www.v2fly.org/guide/start.html))

### DevOps & Infrastructure

- [Binary and Source Installation](https://awesome-repositories.com/f/devops-infrastructure/deployment-management/installation-package-management/binary-and-source-installation.md) — Downloads and places precompiled V2Ray binaries into standard system directories for consistent installation. ([source](https://cdn.jsdelivr.net/gh/v2fly/fhs-install-v2ray@master/README.md))
- [FHS-Compliant Deployers](https://awesome-repositories.com/f/devops-infrastructure/linux-deployment-tools/fhs-compliant-deployers.md) — Places V2Ray binaries and configuration files into standard Linux directory paths for consistent cross-distribution layout.
- [Archive-Based Deployments](https://awesome-repositories.com/f/devops-infrastructure/portable-server-deployments/archive-based-deployments.md) — Downloads and extracts precompiled binaries from a compressed archive for server deployment.
- [Systemd Services](https://awesome-repositories.com/f/devops-infrastructure/systemd-services.md) — Generates and registers unit files to manage V2Ray as a persistent background process with automated lifecycle control.
- [Unit File Generators](https://awesome-repositories.com/f/devops-infrastructure/systemd-services/unit-file-generators.md) — Generates a systemd service unit from a template during installation, enabling automatic startup and log management.
- [Complete File Removals](https://awesome-repositories.com/f/devops-infrastructure/configuration-management/file-based-configuration/managed-file-removal/complete-file-removals.md) — Provides a clean uninstall that removes all binaries, data, config, logs, and service files completely. ([source](https://cdn.jsdelivr.net/gh/v2fly/fhs-install-v2ray@master/README.md))
- [Version Pinning Utilities](https://awesome-repositories.com/f/devops-infrastructure/deployment-management-strategies/automation-and-tooling/version-pinning-utilities.md) — Downloads release assets using a specific version tag from the upstream repository for deterministic deployment.

### Networking & Communication

- [Concurrent Protocol Managers](https://awesome-repositories.com/f/networking-communication/concurrent-protocol-managers.md) — Accepts and proxies connections over Socks, HTTP, Shadowsocks, Trojan, Vmess, and VLESS protocols concurrently. ([source](https://www.v2fly.org/))
- [Network Traffic Routing](https://awesome-repositories.com/f/networking-communication/network-traffic-routing.md) — Directs inbound traffic to specific outbound connections based on region or domain to optimize access.
- [Outbound Connection Managers](https://awesome-repositories.com/f/networking-communication/outbound-connection-managers.md) — Defines how the application transmits data to external network destinations using various proxy protocols. ([source](https://www.v2fly.org/config/overview.html))
- [Proxy Deployment Tools](https://awesome-repositories.com/f/networking-communication/proxy-deployment-tools.md) — Automates the deployment of V2Ray proxy binaries and configuration onto Linux servers. ([source](https://www.v2fly.org/guide/start.html))
- [Proxy Protocols](https://awesome-repositories.com/f/networking-communication/proxy-protocols.md) — Handles multiple proxy protocols concurrently, each with a different transport mechanism. ([source](https://www.v2fly.org/))
- [V2Ray Configuration Managers](https://awesome-repositories.com/f/networking-communication/proxy-servers/v2ray-configuration-managers.md) — Installs V2Ray binaries, assets, and systemd service files into standard Linux filesystem paths. ([source](https://cdn.jsdelivr.net/gh/v2fly/fhs-install-v2ray@master/README.md))
- [SOCKS5 Proxies](https://awesome-repositories.com/f/networking-communication/socks5-proxies.md) — A deployment utility for network tools that obfuscate traffic and route data through multiple outbound protocols.
- [Traffic Routing](https://awesome-repositories.com/f/networking-communication/traffic-routing.md) — Directs incoming traffic to specific exit points based on region or domain to optimize performance. ([source](https://www.v2fly.org/en_US/))
- [Traffic Routing Configurations](https://awesome-repositories.com/f/networking-communication/traffic-routing-configurations.md) — Defines network traffic flow using structured JSON files that map inbound listeners to outbound proxy rules.
- [Traffic Routing Rules](https://awesome-repositories.com/f/networking-communication/traffic-routing-rules.md) — Directs incoming traffic to specific outbound connections based on predefined routing rules and policies. ([source](https://www.v2fly.org/config/overview.html))
- [V2Ray Server Deployments](https://awesome-repositories.com/f/networking-communication/tunneling-server-deployments/v2ray-server-deployments.md) — Installs and configures V2Ray binaries on a server following standard filesystem hierarchies for consistent proxying.
- [DNS Forwarding Routing](https://awesome-repositories.com/f/networking-communication/dns-forwarding-routing.md) — Routes DNS queries through an internal client to control domain resolution over the proxy network. ([source](https://www.v2fly.org/config/overview.html))
- [Proxy DNS Routers](https://awesome-repositories.com/f/networking-communication/dns-forwarding-routing/proxy-dns-routers.md) — Routes domain name resolution through V2Ray's internal client to control DNS handling over the proxy.
- [Internal DNS Resolvers](https://awesome-repositories.com/f/networking-communication/dns-resolution-managers/internal-dns-resolvers.md) — Intercepts and resolves domain names via an integrated client to manage routing across diverse network environments.
- [Domain Name Systems](https://awesome-repositories.com/f/networking-communication/domain-name-systems.md) — Translates domain names into IP addresses using an internal client to manage network requests across environments. ([source](https://www.v2fly.org/v5/config/overview.html))
- [Inbound Connection Managers](https://awesome-repositories.com/f/networking-communication/inbound-connection-managers.md) — Specifies how the application accepts incoming network traffic and which protocols to use for listeners. ([source](https://www.v2fly.org/v5/config/overview.html))
- [Weighted Load Balancing](https://awesome-repositories.com/f/networking-communication/load-balancers/weighted-load-balancing.md) — Distributes outgoing network requests across multiple exit points using a weighted algorithm to optimize throughput.
- [Geographic Traffic Routing Rules](https://awesome-repositories.com/f/networking-communication/network-infrastructure-routing/network-routing-traffic-management/network-routing/geographic-traffic-routing-rules.md) — Directs incoming traffic to different outbound proxies based on domain name or geographic region. ([source](https://www.v2fly.org/))
- [Network Stacks](https://awesome-repositories.com/f/networking-communication/network-stacks.md) — Combines multiple transport layers and obfuscation methods to mask network traffic as standard web requests.
- [Network Transport Protocols](https://awesome-repositories.com/f/networking-communication/network-transport-protocols.md) — Specifies the underlying network protocols and methods used to establish connections between servers. ([source](https://www.v2fly.org/config/overview.html))
- [Multi-Protocol Servers](https://awesome-repositories.com/f/networking-communication/network-transport-protocols/multi-protocol-servers.md) — Runs multiple network protocols concurrently, each with its own transport layer. ([source](https://www.v2fly.org/))

### Operating Systems & Systems Programming

- [POSIX-Compliant Shell Scripts](https://awesome-repositories.com/f/operating-systems-systems-programming/terminal-command-line-environments/shells-scripting/posix-compliant-shell-scripts.md) — Uses a POSIX shell script to sequence download, extraction, file placement, and service registration.

### Security & Cryptography

- [Traffic Masking Tools](https://awesome-repositories.com/f/security-cryptography/traffic-masking-tools.md) — Obfuscates traffic to appear as standard web requests, providing replay protection and preventing interference. ([source](https://www.v2fly.org/en_US/))
- [Traffic Obfuscation](https://awesome-repositories.com/f/security-cryptography/traffic-obfuscation.md) — Masks connection traffic as standard website activity and employs packet disguising to avoid detection. ([source](https://www.v2fly.org/))
- [Traffic Obfuscators](https://awesome-repositories.com/f/security-cryptography/traffic-obfuscators.md) — Obfuscates proxy traffic to resemble standard HTTPS web traffic, hiding the node's true purpose. ([source](https://www.v2fly.org/))
- [Protocol Obfuscation](https://awesome-repositories.com/f/security-cryptography/protocol-obfuscation.md) — Combines multiple transport layers and disguising methods to mask network traffic as standard web requests.

### Web Development

- [Directory-to-Route Mappings](https://awesome-repositories.com/f/web-development/directory-to-route-mappings.md) — Maps V2Ray binaries and data files to standard Linux directories for cross-distribution compatibility.