Some checks failed
Bump build.func Revision / bump-revision (push) Has been cancelled
249 lines
9.3 KiB
Markdown
249 lines
9.3 KiB
Markdown
# build.func Environment Variables Reference
|
|
|
|
## Overview
|
|
|
|
This document provides a comprehensive reference of all environment variables used in `build.func`, organized by category and usage context.
|
|
|
|
## Variable Categories
|
|
|
|
### Core Container Variables
|
|
|
|
| Variable | Description | Default | Set In | Used In |
|
|
|----------|-------------|---------|---------|---------|
|
|
| `APP` | Application name (e.g., "plex", "nextcloud") | - | Environment | Throughout |
|
|
| `NSAPP` | Namespace application name | `$APP` | Environment | Throughout |
|
|
| `CTID` | Container ID | - | Environment | Container creation |
|
|
| `CT_TYPE` | Container type ("install" or "update") | "install" | Environment | Entry point |
|
|
| `CT_NAME` | Container name | `$APP` | Environment | Container creation |
|
|
|
|
### Operating System Variables
|
|
|
|
| Variable | Description | Default | Set In | Used In |
|
|
|----------|-------------|---------|---------|---------|
|
|
| `var_os` | Operating system selection | "debian" | base_settings() | OS selection |
|
|
| `var_version` | OS version | "12" | base_settings() | Template selection |
|
|
| `var_template` | Template name | Auto-generated | base_settings() | Template download |
|
|
|
|
### Resource Configuration Variables
|
|
|
|
| Variable | Description | Default | Set In | Used In |
|
|
|----------|-------------|---------|---------|---------|
|
|
| `var_cpu` | CPU cores | "2" | base_settings() | Container creation |
|
|
| `var_ram` | RAM in MB | "2048" | base_settings() | Container creation |
|
|
| `var_disk` | Disk size in GB | "8" | base_settings() | Container creation |
|
|
| `DISK_SIZE` | Disk size (alternative) | `$var_disk` | Environment | Container creation |
|
|
| `CORE_COUNT` | CPU cores (alternative) | `$var_cpu` | Environment | Container creation |
|
|
| `RAM_SIZE` | RAM size (alternative) | `$var_ram` | Environment | Container creation |
|
|
|
|
### Network Configuration Variables
|
|
|
|
| Variable | Description | Default | Set In | Used In |
|
|
|----------|-------------|---------|---------|---------|
|
|
| `var_net` | Network interface | "vmbr0" | base_settings() | Network config |
|
|
| `var_bridge` | Bridge interface | "vmbr0" | base_settings() | Network config |
|
|
| `var_gateway` | Gateway IP | "192.168.1.1" | base_settings() | Network config |
|
|
| `var_ip` | Container IP address | - | User input | Network config |
|
|
| `var_ipv6` | IPv6 address | - | User input | Network config |
|
|
| `var_vlan` | VLAN ID | - | User input | Network config |
|
|
| `var_mtu` | MTU size | "1500" | base_settings() | Network config |
|
|
| `var_mac` | MAC address | Auto-generated | base_settings() | Network config |
|
|
| `NET` | Network interface (alternative) | `$var_net` | Environment | Network config |
|
|
| `BRG` | Bridge interface (alternative) | `$var_bridge` | Environment | Network config |
|
|
| `GATE` | Gateway IP (alternative) | `$var_gateway` | Environment | Network config |
|
|
| `IPV6_METHOD` | IPv6 configuration method | "none" | Environment | Network config |
|
|
| `VLAN` | VLAN ID (alternative) | `$var_vlan` | Environment | Network config |
|
|
| `MTU` | MTU size (alternative) | `$var_mtu` | Environment | Network config |
|
|
| `MAC` | MAC address (alternative) | `$var_mac` | Environment | Network config |
|
|
|
|
### Storage Configuration Variables
|
|
|
|
| Variable | Description | Default | Set In | Used In |
|
|
|----------|-------------|---------|---------|---------|
|
|
| `var_template_storage` | Storage for templates | - | select_storage() | Template storage |
|
|
| `var_container_storage` | Storage for container disks | - | select_storage() | Container storage |
|
|
| `TEMPLATE_STORAGE` | Template storage (alternative) | `$var_template_storage` | Environment | Template storage |
|
|
| `CONTAINER_STORAGE` | Container storage (alternative) | `$var_container_storage` | Environment | Container storage |
|
|
|
|
### Feature Flags
|
|
|
|
| Variable | Description | Default | Set In | Used In |
|
|
|----------|-------------|---------|---------|---------|
|
|
| `ENABLE_FUSE` | Enable FUSE support | "true" | base_settings() | Container features |
|
|
| `ENABLE_TUN` | Enable TUN/TAP support | "true" | base_settings() | Container features |
|
|
| `ENABLE_KEYCTL` | Enable keyctl support | "true" | base_settings() | Container features |
|
|
| `ENABLE_MOUNT` | Enable mount support | "true" | base_settings() | Container features |
|
|
| `ENABLE_NESTING` | Enable nesting support | "false" | base_settings() | Container features |
|
|
| `ENABLE_PRIVILEGED` | Enable privileged mode | "false" | base_settings() | Container features |
|
|
| `ENABLE_UNPRIVILEGED` | Enable unprivileged mode | "true" | base_settings() | Container features |
|
|
| `VERBOSE` | Enable verbose output | "false" | Environment | Logging |
|
|
| `SSH` | Enable SSH key provisioning | "true" | base_settings() | SSH setup |
|
|
|
|
### GPU Passthrough Variables
|
|
|
|
| Variable | Description | Default | Set In | Used In |
|
|
|----------|-------------|---------|---------|---------|
|
|
| `GPU_APPS` | List of apps that support GPU | - | Environment | GPU detection |
|
|
| `var_gpu` | GPU selection | - | User input | GPU passthrough |
|
|
| `var_gpu_type` | GPU type (intel/amd/nvidia) | - | detect_gpu_devices() | GPU passthrough |
|
|
| `var_gpu_devices` | GPU device list | - | detect_gpu_devices() | GPU passthrough |
|
|
|
|
### API and Diagnostics Variables
|
|
|
|
| Variable | Description | Default | Set In | Used In |
|
|
|----------|-------------|---------|---------|---------|
|
|
| `DIAGNOSTICS` | Enable diagnostics mode | "false" | Environment | Diagnostics |
|
|
| `METHOD` | Installation method | "install" | Environment | Installation flow |
|
|
| `RANDOM_UUID` | Random UUID for tracking | - | Environment | Logging |
|
|
| `API_TOKEN` | Proxmox API token | - | Environment | API calls |
|
|
| `API_USER` | Proxmox API user | - | Environment | API calls |
|
|
|
|
### Settings Persistence Variables
|
|
|
|
| Variable | Description | Default | Set In | Used In |
|
|
|----------|-------------|---------|---------|---------|
|
|
| `SAVE_DEFAULTS` | Save settings as defaults | "false" | User input | Settings persistence |
|
|
| `SAVE_APP_DEFAULTS` | Save app-specific defaults | "false" | User input | Settings persistence |
|
|
| `DEFAULT_VARS_FILE` | Path to default.vars | "/usr/local/community-scripts/default.vars" | Environment | Settings persistence |
|
|
| `APP_DEFAULTS_FILE` | Path to app.vars | "/usr/local/community-scripts/defaults/$APP.vars" | Environment | Settings persistence |
|
|
|
|
## Variable Precedence Chain
|
|
|
|
Variables are resolved in the following order (highest to lowest priority):
|
|
|
|
1. **Hard Environment Variables**: Set before script execution
|
|
2. **App-specific .vars file**: `/usr/local/community-scripts/defaults/<app>.vars`
|
|
3. **Global default.vars file**: `/usr/local/community-scripts/default.vars`
|
|
4. **Built-in defaults**: Set in `base_settings()` function
|
|
|
|
## Critical Variables for Non-Interactive Use
|
|
|
|
For silent/non-interactive execution, these variables must be set:
|
|
|
|
```bash
|
|
# Core container settings
|
|
export APP="plex"
|
|
export CTID="100"
|
|
export var_hostname="plex-server"
|
|
|
|
# OS selection
|
|
export var_os="debian"
|
|
export var_version="12"
|
|
|
|
# Resource allocation
|
|
export var_cpu="4"
|
|
export var_ram="4096"
|
|
export var_disk="20"
|
|
|
|
# Network configuration
|
|
export var_net="vmbr0"
|
|
export var_gateway="192.168.1.1"
|
|
export var_ip="192.168.1.100"
|
|
|
|
# Storage selection
|
|
export var_template_storage="local"
|
|
export var_container_storage="local"
|
|
|
|
# Feature flags
|
|
export ENABLE_FUSE="true"
|
|
export ENABLE_TUN="true"
|
|
export SSH="true"
|
|
```
|
|
|
|
## Environment Variable Usage Patterns
|
|
|
|
### 1. Container Creation
|
|
```bash
|
|
# Basic container creation
|
|
export APP="nextcloud"
|
|
export CTID="101"
|
|
export var_hostname="nextcloud-server"
|
|
export var_os="debian"
|
|
export var_version="12"
|
|
export var_cpu="2"
|
|
export var_ram="2048"
|
|
export var_disk="10"
|
|
export var_net="vmbr0"
|
|
export var_gateway="192.168.1.1"
|
|
export var_ip="192.168.1.101"
|
|
export var_template_storage="local"
|
|
export var_container_storage="local"
|
|
```
|
|
|
|
### 2. GPU Passthrough
|
|
```bash
|
|
# Enable GPU passthrough
|
|
export GPU_APPS="plex,jellyfin,emby"
|
|
export var_gpu="intel"
|
|
export ENABLE_PRIVILEGED="true"
|
|
```
|
|
|
|
### 3. Advanced Network Configuration
|
|
```bash
|
|
# VLAN and IPv6 configuration
|
|
export var_vlan="100"
|
|
export var_ipv6="2001:db8::100"
|
|
export IPV6_METHOD="static"
|
|
export var_mtu="9000"
|
|
```
|
|
|
|
### 4. Storage Configuration
|
|
```bash
|
|
# Custom storage locations
|
|
export var_template_storage="nfs-storage"
|
|
export var_container_storage="ssd-storage"
|
|
```
|
|
|
|
## Variable Validation
|
|
|
|
The script validates variables at several points:
|
|
|
|
1. **Container ID validation**: Must be unique and within valid range
|
|
2. **IP address validation**: Must be valid IPv4/IPv6 format
|
|
3. **Storage validation**: Must exist and support required content types
|
|
4. **Resource validation**: Must be within reasonable limits
|
|
5. **Network validation**: Must be valid network configuration
|
|
|
|
## Common Variable Combinations
|
|
|
|
### Development Container
|
|
```bash
|
|
export APP="dev-container"
|
|
export CTID="200"
|
|
export var_hostname="dev-server"
|
|
export var_os="ubuntu"
|
|
export var_version="22.04"
|
|
export var_cpu="4"
|
|
export var_ram="4096"
|
|
export var_disk="20"
|
|
export ENABLE_NESTING="true"
|
|
export ENABLE_PRIVILEGED="true"
|
|
```
|
|
|
|
### Media Server with GPU
|
|
```bash
|
|
export APP="plex"
|
|
export CTID="300"
|
|
export var_hostname="plex-server"
|
|
export var_os="debian"
|
|
export var_version="12"
|
|
export var_cpu="6"
|
|
export var_ram="8192"
|
|
export var_disk="50"
|
|
export GPU_APPS="plex"
|
|
export var_gpu="nvidia"
|
|
export ENABLE_PRIVILEGED="true"
|
|
```
|
|
|
|
### Lightweight Service
|
|
```bash
|
|
export APP="nginx"
|
|
export CTID="400"
|
|
export var_hostname="nginx-proxy"
|
|
export var_os="alpine"
|
|
export var_version="3.18"
|
|
export var_cpu="1"
|
|
export var_ram="512"
|
|
export var_disk="2"
|
|
export ENABLE_UNPRIVILEGED="true"
|
|
```
|