mirror of
https://github.com/community-scripts/ProxmoxVE.git
synced 2026-02-15 17:53:25 +01:00
Docs: add GPU/TUN, update endpoints & tool refs
Documentation updates across guides and function references: - Added var_gpu and var_tun configuration entries to CONFIGURATION_REFERENCE (GPU passthrough and TUN/TAP support), including features and prerequisites. - Fixed repository URLs throughout UNATTENDED_DEPLOYMENTS and examples: replaced community-scripts/ProxmoxVED with community-scripts/ProxmoxVE and updated curl usage to the new paths. - Added an "Advanced Configuration Variables" table and examples (var_os, var_version, var_gpu, var_tun, var_nesting) to UNATTENDED_DEPLOYMENTS; adjusted sample apps, hostnames, and container mappings in batch examples. - Switched API endpoints in API_FUNCTIONS_REFERENCE and API_USAGE_EXAMPLES from http://api.community-scripts.org to https://api.community-scripts.org. - Expanded BUILD_FUNC_FUNCTIONS_REFERENCE with container resource/ID management helper descriptions (validate_container_id, get_valid_container_id, maxkeys_check, get_current_ip, update_motd_ip). - Large edits to TOOLS_FUNC_FUNCTIONS_REFERENCE: renamed/refactored helper signatures and docs (pkg_install -> install_packages_with_retry, pkg_update -> upgrade_packages_with_retry), added new tooling functions (fetch_and_deploy_gh_release, check_for_gh_release, prepare_repository_setup, verify_tool_version) and updated examples and feature notes. - Updated vm/README.md to list additional VM scripts (new and reorganized examples). These are documentation-only changes to clarify configuration options, correct links and endpoints, and expand the reference material for tooling and build helpers.
This commit is contained in:
CanbiZ (MickLesk)
@@ -56,7 +56,7 @@ get_error_description 255 # "Unknown critical error, often due to missing perm
|
||||
- `DIAGNOSTICS` must be set to "yes"
|
||||
- `RANDOM_UUID` must be set and not empty
|
||||
|
||||
**API Endpoint**: `http://api.community-scripts.org/dev/upload`
|
||||
**API Endpoint**: `https://api.community-scripts.org/dev/upload`
|
||||
|
||||
**JSON Payload Structure**:
|
||||
```json
|
||||
@@ -110,7 +110,7 @@ post_to_api
|
||||
- `curl` command must be available
|
||||
- `RANDOM_UUID` must be set and not empty
|
||||
|
||||
**API Endpoint**: `http://api.community-scripts.org/dev/upload`
|
||||
**API Endpoint**: `https://api.community-scripts.org/dev/upload`
|
||||
|
||||
**JSON Payload Structure**:
|
||||
```json
|
||||
@@ -167,7 +167,7 @@ post_to_api_vm
|
||||
- `RANDOM_UUID` must be set and not empty
|
||||
- POST_UPDATE_DONE must be false (prevents duplicates)
|
||||
|
||||
**API Endpoint**: `http://api.community-scripts.org/dev/upload/updatestatus`
|
||||
**API Endpoint**: `https://api.community-scripts.org/dev/upload/updatestatus`
|
||||
|
||||
**JSON Payload Structure**:
|
||||
```json
|
||||
|
||||
@@ -461,7 +461,7 @@ check_api_health() {
|
||||
echo "Error description test: $test_error"
|
||||
|
||||
# Test API connectivity (without sending data)
|
||||
local api_url="http://api.community-scripts.org/dev/upload"
|
||||
local api_url="https://api.community-scripts.org/dev/upload"
|
||||
if curl -s --head "$api_url" >/dev/null 2>&1; then
|
||||
echo "API endpoint is reachable"
|
||||
else
|
||||
|
||||
@@ -438,6 +438,34 @@ default_var_settings() # Save global defaults
|
||||
maybe_offer_save_app_defaults() # Save app defaults
|
||||
```
|
||||
|
||||
### Container Resource & ID Management
|
||||
|
||||
#### `validate_container_id()`
|
||||
**Purpose**: Validates if a container ID is available for use.
|
||||
**Parameters**: `ctid` (Integer)
|
||||
**Returns**: `0` if available, `1` if already in use or invalid.
|
||||
**Description**: Checks for existing config files in `/etc/pve/lxc/` or `/etc/pve/qemu-server/`, and verifies LVM logical volumes.
|
||||
|
||||
#### `get_valid_container_id()`
|
||||
**Purpose**: Returns the next available, unused container ID.
|
||||
**Parameters**: `suggested_id` (Optional)
|
||||
**Returns**: A valid container ID string.
|
||||
**Description**: If the suggested ID is taken, it increments until it finds an available one.
|
||||
|
||||
#### `maxkeys_check()`
|
||||
**Purpose**: Ensures host kernel parameters support high numbers of keys (required for some apps).
|
||||
**Parameters**: None
|
||||
**Description**: Checks and optionally updates `kernel.keys.maxkeys` and `kernel.keys.maxbytes`.
|
||||
|
||||
#### `get_current_ip()`
|
||||
**Purpose**: Retrieves the current IP address of the container.
|
||||
**Parameters**: `ctid` (Integer)
|
||||
**Returns**: IP address string.
|
||||
|
||||
#### `update_motd_ip()`
|
||||
**Purpose**: Updates the Message of the Day (MOTD) file with the container's IP.
|
||||
**Parameters**: None
|
||||
|
||||
## Function Error Handling
|
||||
|
||||
### Validation Functions
|
||||
|
||||
@@ -60,13 +60,13 @@ Complete alphabetical reference of all functions in tools.func with parameters,
|
||||
|
||||
## Core Functions
|
||||
|
||||
### pkg_install()
|
||||
### install_packages_with_retry()
|
||||
|
||||
Install one or more packages safely with automatic retry logic and error handling.
|
||||
Install one or more packages safely with automatic retry logic (3 attempts), APT refresh, and lock handling.
|
||||
|
||||
**Signature**:
|
||||
```bash
|
||||
pkg_install PACKAGE1 [PACKAGE2 ...]
|
||||
install_packages_with_retry PACKAGE1 [PACKAGE2 ...]
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
@@ -74,112 +74,107 @@ pkg_install PACKAGE1 [PACKAGE2 ...]
|
||||
|
||||
**Returns**:
|
||||
- `0` - All packages installed successfully
|
||||
- `1` - Installation failed after retries
|
||||
- `1` - Installation failed after all retries
|
||||
|
||||
**Features**:
|
||||
- Automatically sets `DEBIAN_FRONTEND=noninteractive`
|
||||
- Handles DPKG lock errors with `dpkg --configure -a`
|
||||
- Retries on transient network or APT failures
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
install_packages_with_retry curl wget git
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### upgrade_packages_with_retry()
|
||||
|
||||
Upgrades installed packages with the same robust retry logic as the installation helper.
|
||||
|
||||
**Signature**:
|
||||
```bash
|
||||
upgrade_packages_with_retry
|
||||
```
|
||||
|
||||
**Returns**:
|
||||
- `0` - Upgrade successful
|
||||
- `1` - Upgrade failed
|
||||
|
||||
---
|
||||
|
||||
### fetch_and_deploy_gh_release()
|
||||
|
||||
The primary tool for downloading and installing software from GitHub Releases. Supports binaries, tarballs, and Debian packages.
|
||||
|
||||
**Signature**:
|
||||
```bash
|
||||
fetch_and_deploy_gh_release APPREPO TYPE [VERSION] [DEST] [ASSET_PATTERN]
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
- `APPREPO`: GitHub repository (e.g., `owner/repo`)
|
||||
- `TYPE`: Asset type (`binary`, `tarball`, `prebuild`, `singlefile`, `binary_tarball`)
|
||||
- `VERSION`: Specific tag or `latest` (Default: `latest`)
|
||||
- `DEST`: Target directory (Default: `/opt/$APP`)
|
||||
- `ASSET_PATTERN`: Regex or string pattern to match the release asset
|
||||
|
||||
**Environment Variables**:
|
||||
- `$STD` - Output suppression (`silent` or empty)
|
||||
- `CLEAN_INSTALL=1`: Removes the destination directory before extracting.
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
pkg_install curl wget git
|
||||
fetch_and_deploy_gh_release "muesli/duf" "binary" "latest" "/opt/duf" "duf_.*_linux_amd64.tar.gz"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### pkg_update()
|
||||
### check_for_gh_release()
|
||||
|
||||
Update package lists with automatic retry logic for network failures.
|
||||
Checks if a newer version is available on GitHub compared to the installed version.
|
||||
|
||||
**Signature**:
|
||||
```bash
|
||||
pkg_update
|
||||
check_for_gh_release APP REPO
|
||||
```
|
||||
|
||||
**Parameters**: None
|
||||
|
||||
**Returns**:
|
||||
- `0` - Package lists updated
|
||||
- `1` - Failed after 3 retries
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
pkg_update
|
||||
if check_for_gh_release "nodejs" "nodesource/distributions"; then
|
||||
# update logic
|
||||
fi
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### pkg_remove()
|
||||
### prepare_repository_setup()
|
||||
|
||||
Remove packages completely including dependencies.
|
||||
Performs safe repository preparation by cleaning up old files, keyrings, and ensuring the APT system is in a working state.
|
||||
|
||||
**Signature**:
|
||||
```bash
|
||||
pkg_remove PACKAGE1 [PACKAGE2 ...]
|
||||
prepare_repository_setup REPO_NAME [REPO_NAME2 ...]
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
- `PACKAGE1, PACKAGE2, ...` - Package names to remove
|
||||
|
||||
**Returns**:
|
||||
- `0` - Packages removed
|
||||
- `1` - Removal failed
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
pkg_remove old-package outdated-tool
|
||||
prepare_repository_setup "mariadb" "mysql"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### setup_deb822_repo()
|
||||
### verify_tool_version()
|
||||
|
||||
Add repository in modern deb822 format (recommended over legacy format).
|
||||
Validates if the installed major version matches the expected version.
|
||||
|
||||
**Signature**:
|
||||
```bash
|
||||
setup_deb822_repo REPO_URL NAME DIST MAIN_URL RELEASE
|
||||
verify_tool_version NAME EXPECTED INSTALLED
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
- `REPO_URL` - URL to GPG key (e.g., https://example.com/key.gpg)
|
||||
- `NAME` - Repository name (e.g., "nodejs")
|
||||
- `DIST` - Distribution (jammy, bookworm, etc.)
|
||||
- `MAIN_URL` - Main repository URL
|
||||
- `RELEASE` - Release type (main, testing, etc.)
|
||||
|
||||
**Returns**:
|
||||
- `0` - Repository added successfully
|
||||
- `1` - Repository setup failed
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
setup_deb822_repo \
|
||||
"https://deb.nodesource.com/gpgkey/nodesource.gpg.key" \
|
||||
"nodejs" \
|
||||
"jammy" \
|
||||
"https://deb.nodesource.com/node_20.x" \
|
||||
"main"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### cleanup_repo_metadata()
|
||||
|
||||
Clean up GPG keys and old repository configurations.
|
||||
|
||||
**Signature**:
|
||||
```bash
|
||||
cleanup_repo_metadata
|
||||
```
|
||||
|
||||
**Parameters**: None
|
||||
|
||||
**Returns**:
|
||||
- `0` - Cleanup complete
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
cleanup_repo_metadata
|
||||
verify_tool_version "nodejs" "22" "$(node -v | grep -oP '^v\K[0-9]+')"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user