CyberMind-FR
78d84ec74f
- Complete guide for PKG_FILE_MODES configuration - Standard comment block template for all modules - File permission reference table (755 for RPCD, 644 for others) - Common errors and solutions - Validation and troubleshooting guides - Best practices for development Covers: - RPCD scripts (755 - CRITICAL for ubus calls) - Helper scripts (755 for executables) - Config files (644 - auto-set) - CSS/JS files (644 - auto-set by luci.mk) - Multi-line PKG_FILE_MODES syntax Reference for all SecuBox developers.
335 lines
8.4 KiB
Markdown
335 lines
8.4 KiB
Markdown
# Makefile Standards for SecuBox LuCI Applications
|
|
|
|
**Version:** 1.0.0
|
|
**Last Updated:** 2025-12-28
|
|
**Status:** Active Standard
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
This document defines the standardized structure and conventions for all `luci-app-*` Makefile configurations in the SecuBox project. Following these standards ensures consistency, maintainability, and proper functionality across all modules.
|
|
|
|
---
|
|
|
|
## File Permissions (PKG_FILE_MODES)
|
|
|
|
### Purpose
|
|
The `PKG_FILE_MODES` variable explicitly sets file ownership and permissions for files installed by the package. This is **CRITICAL** for proper module functionality.
|
|
|
|
### Standard Comment Block
|
|
|
|
All Makefiles **MUST** include this comment block before `PKG_FILE_MODES`:
|
|
|
|
```makefile
|
|
# File permissions (CRITICAL: RPCD scripts MUST be executable 755)
|
|
# Format: path:owner:group:mode
|
|
# - RPCD scripts: 755 (executable by root, required for ubus calls)
|
|
# - Helper scripts: 755 (if executable)
|
|
# - Config files: 644 (readable by all, writable by root)
|
|
# - CSS/JS files: 644 (set automatically by luci.mk)
|
|
```
|
|
|
|
### Format
|
|
|
|
```makefile
|
|
PKG_FILE_MODES:=<path>:<owner>:<group>:<mode>
|
|
```
|
|
|
|
### Required File Modes
|
|
|
|
#### 1. RPCD Scripts (755 - CRITICAL)
|
|
|
|
**Path Pattern:** `/usr/libexec/rpcd/luci.<module-name>`
|
|
|
|
**Mode:** `755` (rwxr-xr-x)
|
|
|
|
**Rationale:**
|
|
- RPCD scripts MUST be executable by root
|
|
- Required for ubus RPC calls from the frontend
|
|
- Without 755, the backend will fail silently
|
|
- Validation: `./secubox-tools/validate-modules.sh` checks this
|
|
|
|
**Example:**
|
|
```makefile
|
|
PKG_FILE_MODES:=/usr/libexec/rpcd/luci.system-hub:root:root:755
|
|
```
|
|
|
|
#### 2. Helper Scripts (755 - If Applicable)
|
|
|
|
**Path Pattern:** `/usr/libexec/<module-name>/*.sh`
|
|
|
|
**Mode:** `755` (rwxr-xr-x)
|
|
|
|
**Rationale:**
|
|
- Shell scripts that need execution permissions
|
|
- Used for cron jobs, maintenance tasks, or utilities
|
|
|
|
**Example:**
|
|
```makefile
|
|
PKG_FILE_MODES:=/usr/libexec/rpcd/luci.secubox:root:root:755 \
|
|
/usr/libexec/secubox/fix-permissions.sh:root:root:755
|
|
```
|
|
|
|
#### 3. Configuration Files (644 - Default)
|
|
|
|
**Path Pattern:** `/etc/config/<module-name>`
|
|
|
|
**Mode:** `644` (rw-r--r--)
|
|
|
|
**Rationale:**
|
|
- UCI config files are world-readable
|
|
- Only root can write
|
|
- Set automatically by OpenWrt, no explicit PKG_FILE_MODES needed
|
|
|
|
#### 4. CSS/JS Files (644 - Automatic)
|
|
|
|
**Path Pattern:** `/www/luci-static/resources/**/*.{css,js}`
|
|
|
|
**Mode:** `644` (rw-r--r--)
|
|
|
|
**Rationale:**
|
|
- Web assets must be readable by all users
|
|
- Set automatically by `luci.mk`
|
|
- **DO NOT** add to PKG_FILE_MODES (redundant)
|
|
|
|
---
|
|
|
|
## Multi-Line PKG_FILE_MODES
|
|
|
|
When specifying multiple files, use backslash continuation:
|
|
|
|
```makefile
|
|
PKG_FILE_MODES:=/usr/libexec/rpcd/luci.secubox:root:root:755 \
|
|
/usr/libexec/secubox/fix-permissions.sh:root:root:755 \
|
|
/usr/libexec/secubox/health-check.sh:root:root:755
|
|
```
|
|
|
|
**Rules:**
|
|
- Backslash `\` at end of line for continuation
|
|
- Indent continuation lines with TAB
|
|
- Last line has NO backslash
|
|
- One space between backslash and newline
|
|
|
|
---
|
|
|
|
## Common Errors and Solutions
|
|
|
|
### Error 1: RPCD Backend Not Responding
|
|
|
|
**Symptom:**
|
|
```
|
|
RPC call to luci.module-name/method failed with error -32000: Object not found
|
|
```
|
|
|
|
**Cause:** RPCD script not executable (missing 755 permissions)
|
|
|
|
**Solution:**
|
|
```makefile
|
|
PKG_FILE_MODES:=/usr/libexec/rpcd/luci.module-name:root:root:755
|
|
```
|
|
|
|
**Validation:**
|
|
```bash
|
|
./secubox-tools/validate-modules.sh
|
|
# OR
|
|
./secubox-tools/fix-permissions.sh --local
|
|
```
|
|
|
|
---
|
|
|
|
### Error 2: CSS/JS Files Added to PKG_FILE_MODES
|
|
|
|
**Wrong:**
|
|
```makefile
|
|
PKG_FILE_MODES:=/usr/libexec/rpcd/luci.system-hub:root:root:755 \
|
|
/www/luci-static/resources/system-hub/api.js:root:root:644
|
|
```
|
|
|
|
**Right:**
|
|
```makefile
|
|
# CSS/JS files are automatically set by luci.mk
|
|
PKG_FILE_MODES:=/usr/libexec/rpcd/luci.system-hub:root:root:755
|
|
```
|
|
|
|
**Rationale:** The LuCI build system (`luci.mk`) automatically sets correct permissions for all files in `/www/`. Adding them to `PKG_FILE_MODES` is redundant and can cause conflicts.
|
|
|
|
---
|
|
|
|
### Error 3: Missing Comment Block
|
|
|
|
**Wrong:**
|
|
```makefile
|
|
LUCI_PKGARCH:=all
|
|
|
|
PKG_FILE_MODES:=/usr/libexec/rpcd/luci.system-hub:root:root:755
|
|
```
|
|
|
|
**Right:**
|
|
```makefile
|
|
LUCI_PKGARCH:=all
|
|
|
|
# File permissions (CRITICAL: RPCD scripts MUST be executable 755)
|
|
# Format: path:owner:group:mode
|
|
# - RPCD scripts: 755 (executable by root, required for ubus calls)
|
|
# - Helper scripts: 755 (if executable)
|
|
# - Config files: 644 (readable by all, writable by root)
|
|
# - CSS/JS files: 644 (set automatically by luci.mk)
|
|
PKG_FILE_MODES:=/usr/libexec/rpcd/luci.system-hub:root:root:755
|
|
```
|
|
|
|
---
|
|
|
|
## Validation Tools
|
|
|
|
### Automated Validation
|
|
|
|
**Before Commit:**
|
|
```bash
|
|
./secubox-tools/validate-modules.sh
|
|
```
|
|
|
|
Checks:
|
|
1. RPCD script names match ubus objects
|
|
2. Menu paths match view file locations
|
|
3. View files have menu entries
|
|
4. **RPCD scripts are executable (755)**
|
|
5. JSON syntax validation
|
|
6. ubus object naming convention
|
|
7. **htdocs file permissions (644 for CSS/JS)**
|
|
|
|
**Auto-Fix Permissions:**
|
|
```bash
|
|
# Fix local files before build
|
|
./secubox-tools/fix-permissions.sh --local
|
|
|
|
# Fix deployed files on router
|
|
./secubox-tools/fix-permissions.sh --remote
|
|
```
|
|
|
|
---
|
|
|
|
## Complete Makefile Template
|
|
|
|
```makefile
|
|
include $(TOPDIR)/rules.mk
|
|
|
|
PKG_NAME:=luci-app-module-name
|
|
PKG_VERSION:=0.3.5
|
|
PKG_RELEASE:=1
|
|
PKG_LICENSE:=Apache-2.0
|
|
PKG_MAINTAINER:=CyberMind <contact@cybermind.fr>
|
|
|
|
LUCI_TITLE:=Module Title - Short Description
|
|
LUCI_DESCRIPTION:=Comprehensive description of module functionality
|
|
LUCI_DEPENDS:=+luci-base +rpcd +optional-dependency
|
|
LUCI_PKGARCH:=all
|
|
|
|
# File permissions (CRITICAL: RPCD scripts MUST be executable 755)
|
|
# Format: path:owner:group:mode
|
|
# - RPCD scripts: 755 (executable by root, required for ubus calls)
|
|
# - Helper scripts: 755 (if executable)
|
|
# - Config files: 644 (readable by all, writable by root)
|
|
# - CSS/JS files: 644 (set automatically by luci.mk)
|
|
PKG_FILE_MODES:=/usr/libexec/rpcd/luci.module-name:root:root:755
|
|
|
|
include $(TOPDIR)/feeds/luci/luci.mk
|
|
|
|
# Optional: Config files to preserve on upgrade
|
|
define Package/$(PKG_NAME)/conffiles
|
|
/etc/config/module-name
|
|
endef
|
|
|
|
# call BuildPackage - OpenWrt buildroot signature
|
|
```
|
|
|
|
---
|
|
|
|
## File Mode Reference Table
|
|
|
|
| File Type | Path Pattern | Owner:Group | Mode | Reason |
|
|
|-----------|-------------|-------------|------|--------|
|
|
| RPCD script | `/usr/libexec/rpcd/luci.*` | root:root | 755 | **CRITICAL** - Must be executable for ubus calls |
|
|
| Helper script | `/usr/libexec/*/*.sh` | root:root | 755 | Executable scripts (cron, maintenance) |
|
|
| UCI config | `/etc/config/*` | root:root | 644 | World-readable, root-writable (auto-set) |
|
|
| CSS/JS files | `/www/luci-static/**/*.{css,js}` | root:root | 644 | Web assets (auto-set by luci.mk) |
|
|
| Menu JSON | `/usr/share/luci/menu.d/*.json` | root:root | 644 | LuCI menu definitions (auto-set) |
|
|
| ACL JSON | `/usr/share/rpcd/acl.d/*.json` | root:root | 644 | Access control lists (auto-set) |
|
|
|
|
---
|
|
|
|
## Best Practices
|
|
|
|
### 1. **Always Validate Before Commit**
|
|
```bash
|
|
./secubox-tools/validate-modules.sh
|
|
```
|
|
|
|
### 2. **Use Standard Comment Block**
|
|
Copy from existing Makefile or this document.
|
|
|
|
### 3. **Only Specify Executable Files**
|
|
Don't add CSS/JS/JSON files to PKG_FILE_MODES.
|
|
|
|
### 4. **Test on Real Hardware**
|
|
Deploy to test router and verify:
|
|
```bash
|
|
ls -la /usr/libexec/rpcd/luci.module-name # Should be -rwxr-xr-x
|
|
ubus list | grep module-name # Should appear
|
|
ubus call luci.module-name status # Should respond
|
|
```
|
|
|
|
### 5. **Document Custom Permissions**
|
|
If adding non-standard file modes, add inline comments explaining why.
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Permission Denied Errors
|
|
|
|
**Check permissions on router:**
|
|
```bash
|
|
ssh root@router "ls -la /usr/libexec/rpcd/luci.*"
|
|
```
|
|
|
|
**Fix remotely:**
|
|
```bash
|
|
./secubox-tools/fix-permissions.sh --remote
|
|
```
|
|
|
|
### Files Not Installed
|
|
|
|
**Check package contents:**
|
|
```bash
|
|
tar -tzf luci-app-module-name_*.ipk | grep rpcd
|
|
# OR (for .apk format)
|
|
tar -tzf luci-app-module-name_*.apk | grep rpcd
|
|
```
|
|
|
|
**Verify Makefile paths:**
|
|
Ensure `PKG_FILE_MODES` paths match actual file locations in the package.
|
|
|
|
---
|
|
|
|
## References
|
|
|
|
- [OpenWrt Makefile Documentation](https://openwrt.org/docs/guide-developer/packages)
|
|
- [LuCI Build System](https://github.com/openwrt/luci/blob/master/luci.mk)
|
|
- [DEVELOPMENT-GUIDELINES.md](./DEVELOPMENT-GUIDELINES.md)
|
|
- [QUICK-START.md](./QUICK-START.md)
|
|
|
|
---
|
|
|
|
## Changelog
|
|
|
|
### v1.0.0 (2025-12-28)
|
|
- Initial standardization across all 15 SecuBox modules
|
|
- Defined standard comment block format
|
|
- Documented file mode requirements
|
|
- Added validation and troubleshooting sections
|
|
|
|
---
|
|
|
|
**Next Review:** 2026-01-28 (or when adding new modules)
|