[Documentation] Comprehensive OpenWrt Setup Guide for Different Router Models, Architectures, and Configuration Formats
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
- Domain
- documentation, networking
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
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:
- General installation guide.
- Hardware and architecture compatibility table.
- Router-specific installation examples.
- Complete sample configuration files.
- Sample subscription URLs and individual proxy links.
- Documentation of supported configuration standards and formats.
- Configuration validation and conversion instructions, where applicable.
- Network integration and routing examples.
- Service management instructions.
- 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
- No Dockerfile or Docker Compose file
- No pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from hiddify/hiddify-core
-
bug need_attention
Difficulty 4/5 3-5 days Newbie friendliness 25/100
hiddify/hiddify-core#174 ·
-
interesting_feature_todo
Difficulty 4/5 1-2 days Newbie friendliness 45/100
hiddify/hiddify-core#173 ·
-
bug useful
Difficulty 3/5 1-2 days Newbie friendliness 48/100
hiddify/hiddify-core#171 · 5 comments ·
-
useful
Difficulty 4/5 3-5 days Newbie friendliness 35/100
hiddify/hiddify-core#124 ·
-
مشکل در openwrtOpenuseful
Difficulty 4/5 3-5 days Newbie friendliness 35/100
hiddify/hiddify-core#80 ·
All issues in hiddify/hiddify-core
Similar issues
-
ssa: wait errors drop the kstatus message, so health check failures don't say whyPossibly taken @schdief claimed this today. Open
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
Maintainers usually reply within 1 day
-
Pin and verify Security Insights schema in lintinsights targetPossibly taken @imshubham22apr-gif claimed this 5 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
gemaraproj/gemara#618 ·
Maintainers usually reply within 2 days
-
Difficulty 2/5 1-3 hours Newbie friendliness 64/100
a2aproject/a2a-go#597 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
Maintainers usually reply within 4 days
-
scopes: GetAllowedTopics, GetProtectedTopics, and GetScopedTopics include empty topic names and do not trim whitespace charactersPossibly taken @patelshivani2283-lab claimed this today. Open
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
Maintainers usually reply within 1 day