ProxmoxVED/docs/misc/install.func/README.md

install.func Documentation

Overview

The install.func file provides container installation workflow orchestration and fundamental operations for applications deployed inside LXC containers. It handles network setup, OS configuration, connectivity verification, and installation mechanics.

Purpose and Use Cases

• Container Setup: Initialize new container with proper configuration
• Network Verification: Verify IPv4 and IPv6 connectivity
• OS Configuration: Update OS, apply system settings
• Installation Workflow: Orchestrate application installation steps
• Error Handling: Comprehensive signal trapping and error recovery

Quick Reference

Key Function Groups

• Initialization: setting_up_container() - Setup message and environment
• Network: network_check(), verb_ip6() - Connectivity verification
• OS Configuration: update_os() - OS updates and package management
• Installation: motd_ssh(), customize() - Container customization
• Cleanup: cleanup_lxc() - Final container cleanup

Dependencies

• External: curl, apt-get, ping, dns utilities
• Internal: Uses functions from core.func, error_handler.func, tools.func

Integration Points

• Used by: All install/*.sh scripts at startup
• Uses: Environment variables from build.func and core.func
• Provides: Container initialization and management services

Documentation Files

📊 INSTALL_FUNC_FLOWCHART.md

Visual execution flows showing initialization, network checks, and installation workflows.

📚 INSTALL_FUNC_FUNCTIONS_REFERENCE.md

Complete alphabetical reference of all functions with parameters, dependencies, and usage details.

💡 INSTALL_FUNC_USAGE_EXAMPLES.md

Practical examples showing how to use installation functions and common patterns.

🔗 INSTALL_FUNC_INTEGRATION.md

How install.func integrates with other components and provides installation services.

Key Features

Container Initialization

• Environment Setup: Prepare container variables and functions
• Message System: Display installation progress with colored output
• Error Handlers: Setup signal trapping for proper cleanup

Network & Connectivity

• IPv4 Verification: Ping external hosts to verify internet access
• IPv6 Support: Optional IPv6 enablement and verification
• DNS Checking: Verify DNS resolution is working
• Retry Logic: Automatic retries for transient failures

OS Configuration

• Package Updates: Safely update OS package lists
• System Optimization: Disable unnecessary services (wait-online)
• Timezone: Validate and set container timezone
• SSH Setup: Configure SSH daemon and keys

Container Customization

• MOTD: Create custom login message
• Auto-Login: Optional passwordless root login
• Update Script: Register application update function
• Customization Hooks: Application-specific setup

Function Categories

🔹 Core Functions

• setting_up_container() - Display setup message and set environment
• network_check() - Verify network connectivity
• update_os() - Update OS packages with retry logic
• verb_ip6() - Enable IPv6 (optional)

🔹 Configuration Functions

• motd_ssh() - Setup MOTD and SSH configuration
• customize() - Apply container customizations
• cleanup_lxc() - Final cleanup before completion

🔹 Utility Functions

• create_update_script() - Register application update function
• set_timezone() - Configure container timezone
• disable_wait_online() - Disable systemd-networkd-wait-online

Execution Flow

Container Started
    ↓
source $FUNCTIONS_FILE_PATH
    ↓
setting_up_container()           ← Display "Setting up container..."
    ↓
network_check()                  ← Verify internet connectivity
    ↓
update_os()                      ← Update package lists
    ↓
[Application-Specific Installation]
    ↓
motd_ssh()                       ← Configure SSH/MOTD
customize()                      ← Apply customizations
    ↓
cleanup_lxc()                    ← Final cleanup
    ↓
Installation Complete

Common Usage Patterns

Basic Container Setup

#!/usr/bin/env bash
source /dev/stdin <<<"$FUNCTIONS_FILE_PATH"
setting_up_container
network_check
update_os

# ... application installation ...

motd_ssh
customize
cleanup_lxc

With Optional IPv6

#!/usr/bin/env bash
source /dev/stdin <<<"$FUNCTIONS_FILE_PATH"
setting_up_container
verb_ip6  # Enable IPv6
network_check
update_os

# ... installation ...

motd_ssh
customize
cleanup_lxc

With Custom Update Script

#!/usr/bin/env bash
source /dev/stdin <<<"$FUNCTIONS_FILE_PATH"
setting_up_container
network_check
update_os

# ... installation ...

# Register update function
function update_script() {
  # Update logic here
}
export -f update_script

motd_ssh
customize
cleanup_lxc

Best Practices

✅ DO

• Call setting_up_container() at the start
• Check network_check() output before main installation
• Use $STD variable for silent operations
• Call cleanup_lxc() at the very end
• Test network connectivity before critical operations

❌ DON'T

• Skip network verification
• Assume internet is available
• Hardcode container paths
• Use echo instead of msg_* functions
• Forget to call cleanup at the end

Environment Variables

Available Variables

• $FUNCTIONS_FILE_PATH - Path to core functions (set by build.func)
• $CTID - Container ID number
• $NSAPP - Normalized application name (lowercase)
• $APP - Application display name
• $STD - Output suppression (silent or empty)
• $VERBOSE - Verbose output mode (yes or no)

Setting Container Variables

CONTAINER_TIMEZONE="UTC"
CONTAINER_HOSTNAME="myapp-container"
CONTAINER_FQDN="myapp.example.com"

Troubleshooting

"Network check failed"

# Container may not have internet access
# Check:
ping 8.8.8.8           # External connectivity
nslookup example.com   # DNS resolution
ip route show          # Routing table

"Package update failed"

# APT may be locked by another process
ps aux | grep apt      # Check for running apt
# Or wait for existing apt to finish
sleep 30
update_os

"Cannot source functions"

# $FUNCTIONS_FILE_PATH may not be set
# This variable is set by build.func before running install script
# If missing, the install script was not called properly

Related Documentation

• tools.func/ - Package and tool installation
• core.func/ - Utility functions and messaging
• error_handler.func/ - Error handling
• alpine-install.func/ - Alpine-specific setup
• UPDATED_APP-install.md - Application script guide

Recent Updates

Version 2.0 (Dec 2025)

• ✅ Improved network connectivity checks
• ✅ Enhanced OS update error handling
• ✅ Added IPv6 support with verb_ip6()
• ✅ Better timezone validation
• ✅ Streamlined cleanup procedures

---

Last Updated: December 2025 Maintainers: community-scripts team License: MIT