Skip to content

core: support optional POST_INSTALL_SCRIPT (var_post_install_script) hook #14160

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
MickLesk wants to merge 4 commits into
base: main
Choose a base branch
from
+542 −3
Draft

core: support optional POST_INSTALL_SCRIPT (var_post_install_script) hook #14160

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
53fcf17
build.func: add var_post_install (host-side post-install script). Con…
MickLesk May 1, 2026
5432839
build.func(post-install-hook): add advanced-settings step, validation…
MickLesk May 3, 2026
bfdd075
docs(post-install-hook): add example library with 5 complete hook scr…
MickLesk May 3, 2026
21965ee
style(post-install-hook-examples): apply formatter (shfmt)
MickLesk May 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 106 additions & 3 deletions misc/build.func
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1062,6 +1062,7 @@ load_vars_file() {
var_gateway var_hostname var_ipv6_method var_mac var_mknod var_mount_fs var_mtu
var_net var_nesting var_ns var_os var_protection var_pw var_ram var_tags var_timezone var_tun var_unprivileged
var_verbose var_version var_vlan var_ssh var_ssh_authorized_key var_container_storage var_template_storage var_searchdomain
var_post_install
)

# Whitelist check helper
Expand Down Expand Up @@ -1279,6 +1280,7 @@ default_var_settings() {
var_gateway var_hostname var_ipv6_method var_mac var_mknod var_mount_fs var_mtu
var_net var_nesting var_ns var_os var_protection var_pw var_ram var_tags var_timezone var_tun var_unprivileged
var_verbose var_version var_vlan var_ssh var_ssh_authorized_key var_container_storage var_template_storage
var_post_install
)

# Snapshot: environment variables (highest precedence)
Expand Down Expand Up @@ -1374,6 +1376,11 @@ var_verbose=no
# GitHub Personal Access Token (optional – avoids API rate limits during installs)
# Create at https://github.com/settings/tokens – read-only public access is sufficient
# var_github_token=ghp_your_token_here

# Optional post-install script (host-side path to a *.sh on the Proxmox host)
# Runs ON THE HOST after the container is fully provisioned.
# Available env vars: APP, NSAPP, CTID, IP, HN, STORAGE, BRG
# var_post_install=/opt/post-install/myhook.sh
EOF

# Now choose storages (always prompt unless just one exists)
Expand Down Expand Up @@ -1452,6 +1459,7 @@ if ! declare -p VAR_WHITELIST >/dev/null 2>&1; then
var_gateway var_hostname var_ipv6_method var_mac var_mknod var_mount_fs var_mtu
var_net var_nesting var_ns var_os var_protection var_pw var_ram var_tags var_timezone var_tun var_unprivileged
var_verbose var_version var_vlan var_ssh var_ssh_authorized_key var_container_storage var_template_storage var_searchdomain
var_post_install
)
fi

Expand Down Expand Up @@ -1664,6 +1672,7 @@ _build_current_app_vars_tmp() {

[ -n "$_tpl_storage" ] && echo "var_template_storage=$(_sanitize_value "$_tpl_storage")"
[ -n "$_ct_storage" ] && echo "var_container_storage=$(_sanitize_value "$_ct_storage")"
[ -n "${var_post_install:-}" ] && echo "var_post_install=$(_sanitize_value "${var_post_install}")"
} >"$tmpf"

echo "$tmpf"
Expand Down Expand Up @@ -1808,7 +1817,7 @@ advanced_settings() {
TAGS="community-script${var_tags:+;${var_tags}}"
fi
local STEP=1
local MAX_STEP=28
local MAX_STEP=29

# Store values for back navigation - inherit from var_* app defaults
local _ct_type="${var_unprivileged:-1}"
Expand Down Expand Up @@ -1842,6 +1851,7 @@ advanced_settings() {
local _enable_mknod="${var_mknod:-0}"
local _mount_fs="${var_mount_fs:-}"
local _protect_ct="${var_protection:-no}"
local _post_install="${var_post_install:-}"

# Detect host timezone for default (if not set via var_timezone)
local _host_timezone=""
Expand Down Expand Up @@ -2699,9 +2709,61 @@ advanced_settings() {
;;

# ═══════════════════════════════════════════════════════════════════════════
# STEP 28: Verbose Mode & Confirmation
# STEP 28: Optional host-side post-install hook (path on the Proxmox HOST)
# ═══════════════════════════════════════════════════════════════════════════
28)
local _hook_prompt="Optional: absolute path to a *.sh file ON THE PROXMOX HOST.

It runs as root on the HOST (NOT in the LXC) after the container
is fully provisioned and started.

Available env vars: APP, NSAPP, CTID, IP, HN, STORAGE, BRG.

Leave empty to skip."
while true; do
if result=$(whiptail --backtitle "Proxmox VE Helper Scripts [Step $STEP/$MAX_STEP]" \
--title "POST-INSTALL HOOK (HOST)" \
--ok-button "Next" --cancel-button "Back" \
--inputbox "$_hook_prompt" 16 70 "${_post_install}" \
3>&1 1>&2 2>&3); then
# Normalize: strip surrounding whitespace
result="$(printf '%s' "$result" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')"
if [[ -z "$result" ]]; then
_post_install=""
((STEP++))
break
fi
# Reject obvious shell-meta sneaking through
if [[ "$result" == *';'* || "$result" == *'$('* || "$result" == *'`'* || "$result" == *'&&'* || "$result" == *'||'* ]]; then
whiptail --backtitle "Proxmox VE Helper Scripts" --title "INVALID PATH" \
--msgbox "Path contains shell metacharacters. Please provide a plain absolute file path." 10 70
continue
fi
if [[ "$result" != /* ]]; then
whiptail --backtitle "Proxmox VE Helper Scripts" --title "INVALID PATH" \
--msgbox "Path must be absolute (start with /).\n\nGot: $result" 10 70
continue
fi
if [[ ! -f "$result" ]]; then
if ! whiptail --backtitle "Proxmox VE Helper Scripts" --title "FILE NOT FOUND" \
--yesno "File does not exist on host:\n\n$result\n\nKeep this path anyway?" 12 70; then
continue
fi
fi
_post_install="$result"
((STEP++))
break
else
((STEP--))
break
fi
done
;;

# ═══════════════════════════════════════════════════════════════════════════
# STEP 29: Verbose Mode & Confirmation
# ═══════════════════════════════════════════════════════════════════════════
29)
local verbose_default_flag="--defaultno"
[[ "$_verbose" == "yes" ]] && verbose_default_flag=""

Expand Down Expand Up @@ -2730,6 +2792,11 @@ advanced_settings() {
local apt_display="${_apt_cacher:-no}"
[[ "$_apt_cacher" == "yes" && -n "$_apt_cacher_ip" ]] && apt_display="$_apt_cacher_ip"

local post_install_display="${_post_install:-(none)}"
local post_install_warn=""
[[ -n "$_post_install" ]] && post_install_warn="
⚠ Hook runs as root on Proxmox HOST (not in LXC)"

local summary="Container Type: $ct_type_desc
Container ID: $_ct_id
Hostname: $_hostname
Expand All @@ -2753,7 +2820,8 @@ Features:
Advanced:
Timezone: $tz_display
APT Cacher: $apt_display
Verbose: $_verbose"
Verbose: $_verbose
Post-Install Script: ${post_install_display}${post_install_warn}"

if whiptail --backtitle "Proxmox VE Helper Scripts [Step $STEP/$MAX_STEP]" \
--title "CONFIRM SETTINGS" \
Expand Down Expand Up @@ -2796,6 +2864,7 @@ Advanced:
APT_CACHER="$_apt_cacher"
APT_CACHER_IP="$_apt_cacher_ip"
VERBOSE="$_verbose"
var_post_install="$_post_install"

# Update var_* based on user choice (for functions that check these)
var_gpu="$_enable_gpu"
Expand Down Expand Up @@ -6305,6 +6374,40 @@ EOF
systemctl start ping-instances.service
fi

# Optional host-side post-install hook
# Path comes from var_post_install (default.vars / app.vars / advanced settings).
# Runs ON THE PROXMOX HOST after the container is up and configured.
# Exposed env vars: APP, NSAPP, CTID, IP, HN, STORAGE, BRG.
# Output (stdout/stderr) is captured to /var/log/community-scripts/post-install-<CTID>.log
if [[ -n "${var_post_install:-}" ]]; then
local _hook_log_dir="/var/log/community-scripts"
local _hook_log="${_hook_log_dir}/post-install-${CTID}.log"
mkdir -p "$_hook_log_dir" 2>/dev/null || true

if [[ ! -f "${var_post_install}" ]]; then
msg_error "Post-install hook not found on host: ${var_post_install}"
whiptail --backtitle "Proxmox VE Helper Scripts" \
--title "POST-INSTALL HOOK FAILED" \
--msgbox "The configured post-install hook was not found on the Proxmox host:\n\n${var_post_install}\n\nThe LXC was created successfully, but the hook did NOT run." 14 72 || true
else
msg_info "Running post-install hook: ${var_post_install}"
local _hook_rc=0
APP="$APP" NSAPP="${NSAPP:-}" CTID="$CTID" IP="$IP" HN="${HN:-}" \
STORAGE="${STORAGE:-}" BRG="${BRG:-}" \
bash "${var_post_install}" >"${_hook_log}" 2>&1 || _hook_rc=$?
if [[ $_hook_rc -eq 0 ]]; then
msg_ok "Post-install hook completed (log: ${_hook_log})"
else
msg_error "Post-install hook failed (rc=${_hook_rc}) – see ${_hook_log}"
local _hook_tail=""
_hook_tail="$(tail -n 15 "${_hook_log}" 2>/dev/null || true)"
whiptail --backtitle "Proxmox VE Helper Scripts" \
--title "POST-INSTALL HOOK FAILED" \
--msgbox "Hook exited with code ${_hook_rc}.\n\nScript: ${var_post_install}\nLog: ${_hook_log}\n\n--- Last log lines ---\n${_hook_tail}\n\nThe LXC itself was created successfully." 22 78 || true
fi
fi
fi

INSTALL_COMPLETE=true
post_update_to_api "done" "none"
}
Expand Down
Loading
Loading