[Documentation] Comprehensive OpenWrt Setup Guide for Different Router Models, Architectures, and Configuration Formats

Open
#167 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Active
Tech stack
linux

Research direction

Start with the existing guide at https://hiddify.com/app/How-to-use-HiddifyCli-on-OpenWrt/ and check the current OpenWrt support and configuration behavior in the project. The request spans architecture compatibility, installation, configuration and subscriptions, routing, service management, and troubleshooting, so agree on scope and verify each example against supported releases. Done means a dedicated guide with accurate, reproducible instructions and clearly marked placeholders.

Written by the indexing model from the issue text.

Description

documentation interesting_feature_todo

Description

I would like to request comprehensive, step-by-step documentation explaining how to install, configure, and run Hiddify Core on OpenWrt-based routers with different hardware architectures and specifications.

Although Hiddify Core supports OpenWrt, users may encounter difficulties identifying compatible binaries, installing dependencies, configuring the service, importing supported configurations, and routing network traffic through the core.

In particular, the documentation should not be limited to installation instructions. It should also clearly explain the supported configuration formats, subscription link formats, and the exact steps required to obtain, import, validate, and use these configurations on OpenWrt.

Providing complete working examples, including sample configuration files and corresponding subscription links where applicable, would make Hiddify Core significantly easier to deploy and use on different routers.

Proposed Documentation

1. Hardware and Architecture Compatibility

Please document the following:

  • Supported router architectures, including x86_64, ARM64, ARM, and MIPS, wherever applicable.
  • How to identify a router's CPU architecture, installed OpenWrt version, and available system resources.
  • Minimum and recommended RAM, flash storage, and CPU requirements.
  • Compatibility with different OpenWrt releases.
  • Known hardware, firmware, and architecture-specific limitations.

A compatibility table covering common router models and architectures would be particularly helpful.

2. Installation Methods

Please provide detailed instructions for:

  • Installing Hiddify Core using the official installation script.
  • Manual installation using the appropriate precompiled binary.
  • Installing official OpenWrt packages, if available.
  • Installing required dependencies.
  • Choosing the appropriate installation method for different hardware configurations.
  • Resolving common installation errors.

All commands should be tested where possible and accompanied by explanations.

3. Router-Specific Setup Guides

Please include practical examples for different types of OpenWrt devices, such as:

  • x86_64 mini PCs and dedicated router systems.
  • ARM64-based routers.
  • ARM-based routers.
  • MIPS-based routers, where supported.
  • Routers with limited RAM and internal flash storage.

Please clearly distinguish between instructions that apply to all OpenWrt devices and those that are specific to particular architectures or router models.

4. Configuration Formats, Sample Configurations, and Subscription Links

This is one of the most important parts of the requested documentation.

Please provide explicit documentation explaining exactly which configuration formats and subscription links Hiddify Core supports on OpenWrt and how users can obtain and use them.

The documentation should cover the following:

A. Supported Configuration Formats
  • List all officially supported configuration formats.
  • Clarify whether Hiddify Core accepts native configuration files, subscription URLs, individual proxy links, or other configuration formats.
  • Explain whether the core uses a specific configuration schema or format based on sing-box or another underlying component.
  • Clearly distinguish between formats supported directly by Hiddify Core and formats that require conversion or additional processing.
  • Document any differences between the configuration formats accepted by Hiddify Core on OpenWrt and those accepted by the Hiddify application on desktop or mobile platforms.
B. Complete Sample Configuration Files

Please provide at least one complete, working sample configuration for each officially supported configuration format relevant to OpenWrt.

For each example, please explain:

  • The purpose of the configuration file.
  • The required and optional fields.
  • Which fields users need to customize.
  • Where the configuration file should be stored on the router.
  • How to reference the configuration file when starting Hiddify Core.
  • How to validate the configuration and troubleshoot parsing errors.

Examples should be complete enough to help users understand the required structure and adapt the configuration to their own servers.

Please also provide examples for common use cases, such as configuring a proxy outbound, DNS, routing, and TUN mode, wherever supported.

C. Sample Subscription Links and Their Corresponding Configurations

Please provide example subscription URLs and individual proxy links, wherever supported, and explain how they should be used with Hiddify Core on OpenWrt.

In particular, please clarify:

  • Whether Hiddify Core can directly consume a remote subscription URL or whether the subscription must first be converted into a configuration file.
  • Which subscription formats are supported, such as sing-box, Clash, V2Ray, or other formats, if applicable.
  • Whether individual proxy links, such as VLESS, VMess, Trojan, or Shadowsocks links, can be imported directly.
  • Whether a subscription URL and a single proxy configuration URL are handled differently.
  • How to configure subscription updates, if supported.
  • How authentication, URL encoding, and other subscription-specific requirements should be handled.

Please include at least one complete example showing the relationship between a subscription link, its returned configuration data, and the final configuration used by Hiddify Core on OpenWrt.

If a real subscription URL cannot be provided for security or privacy reasons, a clearly identified placeholder URL and representative sample response would be sufficient.

No actual private subscription credentials or personal access tokens should be included in the documentation.

D. Official Configuration Standards and Compatibility

If Hiddify Core uses a specific standard, schema, or custom format for configuration files and subscription links, please document it explicitly.

Please clarify:

  • The exact format and syntax expected by Hiddify Core.
  • Whether the format follows an existing public standard or is project-specific.
  • Which protocol URI schemes and configuration structures are supported.
  • Whether subscription providers must follow any specific formatting requirements.
  • Which formats are unsupported, partially supported, or require conversion.
  • Whether the same configuration can be used across different Hiddify platforms or whether OpenWrt requires a platform-specific configuration.

If no single universal format exists, please provide a compatibility table showing which formats work directly, which require conversion, and which are not supported.

E. Configuration Validation and Troubleshooting

Please explain how users can determine whether a configuration file or subscription link is valid and compatible with their installation.

Include practical troubleshooting instructions for:

  • Invalid configuration syntax.
  • Unsupported configuration formats.
  • Invalid or inaccessible subscription URLs.
  • Missing or unsupported protocol features.
  • Subscription download and update failures.
  • Configuration parsing errors.
  • Differences between a successfully imported configuration and a successfully established connection.
5. Network Integration and Routing

Please document how to integrate Hiddify Core with OpenWrt networking components, including:

  • Configuring the service and its startup parameters.
  • Setting up DNS and routing.
  • Configuring TUN mode and its dependencies, where supported.
  • Integrating with OpenWrt firewall components, including firewall4 and nftables where applicable.
  • Routing LAN client traffic through Hiddify Core.
  • Configuring transparent proxying or other supported routing methods.
  • Avoiding routing conflicts, DNS leaks, and loss of router management access.

Please provide tested examples for common network configurations.

6. Service Management

Please explain how to:

  • Configure Hiddify Core to start automatically at boot.
  • Start, stop, restart, and inspect the service.
  • Configure the service using OpenWrt's service management system.
  • Locate and interpret relevant logs.
  • Update the core without unnecessarily losing configuration data.
  • Safely disable or uninstall the service.
7. Storage and Resource Management

For routers with limited resources, please document:

  • Installing and running Hiddify Core with limited internal flash storage.
  • Using external USB storage where supported.
  • Managing logs, temporary files, and persistent configuration files.
  • Monitoring memory usage, CPU load, and available storage.
  • Reducing unnecessary storage writes where possible.
8. Troubleshooting

Please include a troubleshooting section covering common problems, such as:

  • Unsupported architectures or incompatible binaries.
  • Missing dependencies.
  • Service startup failures.
  • TUN device and permission issues.
  • Invalid or incompatible configurations.
  • Subscription download failures.
  • DNS resolution problems and DNS leaks.
  • Firewall and routing conflicts.
  • Insufficient memory or storage.
  • Unexpected behavior after upgrading OpenWrt or Hiddify Core.

Where possible, include diagnostic commands, example error messages, and corresponding solutions.

9. Version Compatibility and Maintenance

Please document:

  • Compatibility with different OpenWrt releases.
  • Compatibility between Hiddify Core versions and configuration formats.
  • Safe update procedures.
  • Configuration backup and restoration.
  • Known limitations and platform-specific issues.

Suggested Documentation Structure

A dedicated OpenWrt documentation section would be ideal, containing:

  1. General installation guide.
  2. Hardware and architecture compatibility table.
  3. Router-specific installation examples.
  4. Complete sample configuration files.
  5. Sample subscription URLs and individual proxy links.
  6. Documentation of supported configuration standards and formats.
  7. Configuration validation and conversion instructions, where applicable.
  8. Network integration and routing examples.
  9. Service management instructions.
  10. Troubleshooting and maintenance guides.

All examples should clearly indicate which values are placeholders and which commands or configuration fields users must customize.

Where possible, examples should be tested against actual Hiddify Core releases and supported OpenWrt versions.

Expected Benefits

  • Easier installation on different OpenWrt routers.
  • Clearer understanding of supported configuration formats and subscription links.
  • Fewer configuration errors and compatibility issues.
  • Easier integration with existing OpenWrt network configurations.
  • Reduced reliance on trial and error or unofficial tutorials.
  • Better support for users who want to route traffic from their entire LAN through Hiddify Core.
  • Improved accessibility for beginners and advanced users alike.

Additional Context

The existing OpenWrt documentation can serve as the starting point for these improvements:

https://hiddify.com/app/How-to-use-HiddifyCli-on-OpenWrt/

Official repository:

https://github.com/hiddify/hiddify-core

The goal is to expand the existing documentation with comprehensive, practical, and reproducible instructions, especially regarding configuration formats, subscription links, and router-specific deployment.

Thank you for maintaining Hiddify Core and considering this documentation improvement.

Dominant language
Go
Stars
237
Forks
206
Avg merge
3h 44m
Merged PRs (30d)
4

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from hiddify/hiddify-core

All issues in hiddify/hiddify-core

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.