156 lines
5.1 KiB
Markdown
156 lines
5.1 KiB
Markdown
# 📦 Packets – Custom Package Manager for Linux
|
||
|
||
> A fast and minimal package manager written in Go with Lua hooks, local network discovery, and SQLite-based indexing.
|
||
|
||
---
|
||
|
||
## 📘 Overview
|
||
|
||
**Packets** is a lightweight package manager for Linux, written in Go. It supports:
|
||
|
||
- Installation and removal of packages
|
||
- Dependency resolution and upgrading
|
||
- `.tar.zst` compressed packages with `manifest.toml` metadata
|
||
- Lua-based install/remove hooks
|
||
- Local cache with SHA-256 validation
|
||
- Peer-to-peer discovery over LAN
|
||
- Remote package syncing via HTTP
|
||
- SQLite-based local database
|
||
|
||
---
|
||
|
||
## 📁 Directory Structure
|
||
|
||
| Path | Description |
|
||
|-----------------------|----------------------------------|
|
||
| `/etc/packets/` | Configuration files |
|
||
| `/opt/packets/` | Installed package data |
|
||
| `/var/cache/packets/` | Cached `.tar.zst` package files |
|
||
|
||
(This can be changed in `/etc/packets/config.toml`)
|
||
|
||
---
|
||
|
||
# Available Commands
|
||
|
||
| Command | Description |
|
||
|---------------------------|----------------------------------------------------------------------------|
|
||
|`packets install <name>` | Install a package (resolves dependencies, executes Lua install hook) |
|
||
|`packets remove <name>` | Remove a package (executes Lua remove hook) |
|
||
|`packets upgrade <name>` | Upgrade a package by checking family and serial in the manifest |
|
||
|`packets sync [url]` | Synchronize index.db from remote HTTP source |
|
||
|`packets serve init/stop` | Starts and stop the LAN service daemon |
|
||
|`packets list` | List all installed packages |
|
||
|
||
# 📦 Package Format
|
||
|
||
Packages must be compressed as .tar.zst and include:
|
||
|
||
|
||
- ├── manifest.toml # Package metadata
|
||
- ├── data/ # Files to install
|
||
- ├── install.lua # Lua install hook
|
||
- └── remove.lua # Lua remove hook
|
||
|
||
|
||
## Example manifest.toml
|
||
[Info]
|
||
name = "packets"
|
||
version = "1.0.0"
|
||
description = "offline and online packetmanager"
|
||
dependencies = []
|
||
author = "robo"
|
||
family = "1f84ca15-5077-4f1d-a370-0ec860766eb2"
|
||
serial = 0
|
||
|
||
[Hooks]
|
||
install = "install.lua"
|
||
remove = "remove.lua"
|
||
|
||
--
|
||
# 🔄 Installation Process
|
||
|
||
- Check if package is already cached and validated via SHA-256.
|
||
|
||
- If not, search the package:
|
||
|
||
Via LAN: Sends UDP broadcast (Q:filename) to peers.
|
||
|
||
Via HTTP: Downloads from configured mirrors.
|
||
|
||
Decompress .tar.zst, install files.
|
||
|
||
Execute Lua install hook.
|
||
|
||
# 🧩 Core Features
|
||
✅ Dependency Resolution
|
||
|
||
Installs required dependencies listed in the manifest.
|
||
## 🌐 LAN Discovery
|
||
|
||
Broadcasts package request to devices in the same network via UDP.
|
||
## 📡 Remote Download
|
||
|
||
Downloads package via HTTP if not found on LAN.
|
||
## 🔒 Security
|
||
|
||
SHA-256 checksum validation
|
||
|
||
Path validation to avoid exploits (..)
|
||
|
||
Safe, sandboxed Lua runtime with limited API
|
||
|
||
|
||
# 🌍 Global Variables Available in Lua Scripts
|
||
|
||
During the execution of install.lua and remove.lua hooks, some global variables are automatically provided to the Lua environment. These help simplify file path handling and access to package-specific directories.
|
||
## Available variables:
|
||
|
||
|Name |Type | Description
|
||
|--------------------|--------|--------------------------------------------------------------------------|
|
||
|packets_package_dir | string| Absolute path to the package's data directory (e.g., /opt/packets/...) |
|
||
| packets_bin_dir | string| Path where executables should be installed (e.g., /usr/bin) |
|
||
|script | string| Path to the currently executing script (e.g., "install.lua") |
|
||
|data_dir | string| Path to the /data folder of the current package |
|
||
### Example usage in Lua:
|
||
|
||
print("Installing into: " .. packets_bin_dir)
|
||
print("Package data in: " .. data_dir)
|
||
|
||
-- Copy a binary to /usr/bin
|
||
os.copy(path_join(data_dir, "htop"), path_join(packets_bin_dir, "htop"))
|
||
|
||
These variables are preloaded in the Lua environment—no need to manually declare or initialize them.
|
||
|
||
|
||
## 🛠️ Allowed Lua API (install/remove hooks)
|
||
|
||
To ensure security, only a limited set of safe functions are exposed in Lua hooks:
|
||
|
||
os.remove(path)
|
||
os.rename(old, new)
|
||
os.copy(source, target)
|
||
os.symlink(source, target)
|
||
io.open(path, mode)
|
||
path_join(...) -- Safely join path segments
|
||
|
||
### Note: Dangerous functions like os.execute, os.getenv, etc. are removed.
|
||
## 🗃️ Databases
|
||
|
||
index.db: Available packages (after sync)
|
||
|
||
installed.db: Packages currently installed
|
||
|
||
# ⚠️ Restrictions & Notes
|
||
|
||
Linux only (//go:build linux)
|
||
|
||
Root permissions required for most commands
|
||
|
||
Changing dataDir triggers prompt to migrate installed packages
|
||
|
||
Binaries in binDir are not automatically moved if path changes
|
||
|
||
Do not manually edit lastDataDir
|
||
|