Logs

Overview

The Proxmox VE Helper Scripts generate detailed logs throughout container creation and installation processes. Understanding where logs are stored and how to read them is essential for troubleshooting issues.

Log File Locations

Default Log Locations (Without Debug Mode)

Host-Side Logs

Location: /tmp/create-lxc-<SESSION_ID>.logContains:

Container creation process
Template download and verification
Network configuration
Initial container setup

Example:

# View creation log
tail -n 50 /tmp/create-lxc-*.log

# Find latest log
ls -lt /tmp/create-lxc-*.log | head -1

Container Installation Logs

Temporary Location (during install): /root/.install-<SESSION_ID>.log (inside container)Copied to Host on Failure: /tmp/install-lxc-<CTID>-<SESSION_ID>.logContains:

Package installations
Application setup
Database configurations
Service startup
All commands executed inside the container

Example:

# View installation log (after failure)
tail -n 50 /tmp/install-lxc-*-*.log

# While installation is running, enter container:
pct enter <CTID>
tail -f /root/.install-*.log

Persistent Logs (With Debug Mode)

When using dev_mode="logs", logs are saved permanently to /var/log/community-scripts/.

Persistent Log Locations

Host Creation Log: /var/log/community-scripts/create-lxc-<SESSION_ID>-<TIMESTAMP>.logContainer Installation Log: /var/log/community-scripts/install-<SESSION_ID>-<TIMESTAMP>.logFormat:

SESSION_ID: Unique identifier (e.g., abc12345)
TIMESTAMP: Date and time (e.g., 20251117_143022)

Example:

# Enable persistent logging
export dev_mode="logs"
bash -c "$(curl ...)"

# View logs
ls -lh /var/log/community-scripts/
tail -f /var/log/community-scripts/install-*.log

Persistent logs are kept even after successful installations, making them ideal for CI/CD and post-mortem analysis.

Log Types and Contents

Creation Log (create-lxc-*.log)

Contains:

Script initialization
Template selection and validation
Template download (if needed)
Container creation (pct create command)
Network setup
Storage allocation
Initial container start

Example Log Entries:

[2025-11-17 14:30:15] Starting container creation
[2025-11-17 14:30:16] Template: debian-13-standard_13.1-1_amd64.tar.zst
[2025-11-17 14:30:17] Storage: local-lvm
[2025-11-17 14:30:18] CTID: 107
[2025-11-17 14:30:20] Network: vmbr0, DHCP
[2025-11-17 14:30:25] Container 107 created successfully

Installation Log (install-*.log)

Contains:

OS updates (apt update, apt upgrade)
Package installations
Application downloads and extractions
Configuration file modifications
Database setup and migrations
Service configuration and startup
Final cleanup and validation

Example Log Entries:

[2025-11-17 14:31:00] Updating Container OS
[2025-11-17 14:31:15] Installing Dependencies
[2025-11-17 14:31:45] Downloading Wallabag v2.6.9
[2025-11-17 14:32:10] Configuring Database
[2025-11-17 14:32:25] Running Database Migrations
[2025-11-17 14:32:40] Starting Services
[2025-11-17 14:32:45] Installation Complete

Error Log Entries

When errors occur, logs include:

Exit code and explanation
Command that failed
Line number in script
Last 20 lines of execution context

Example Error Entry:

[ERROR] in line 245: exit code 100 (APT: Package manager error): 
while executing command apt-get install -y wallabag
--- Last 20 lines of log ---
...
E: Unable to locate package wallabag
E: Failed to fetch http://deb.debian.org/debian/...

Reading and Analyzing Logs

Real-Time Monitoring

# Monitor creation log
tail -f /tmp/create-lxc-*.log

# Monitor installation log (from inside container)
pct enter <CTID>
tail -f /root/.install-*.log

# Monitor persistent logs
tail -f /var/log/community-scripts/*.log

Searching Logs

# Find all error messages
grep -i "error" /var/log/community-scripts/*.log

# Find specific exit codes
grep "exit code [1-9]" /var/log/community-scripts/*.log

# Find failures
grep -i "fail" /tmp/create-lxc-*.log

Log Analysis Commands

# Show timestamps and major steps
grep "msg_info\|msg_ok\|msg_error" /var/log/community-scripts/*.log

# Calculate installation duration
HEAD_TIME=$(head -1 /tmp/install-*.log | cut -d']' -f1 | cut -d'[' -f2)
TAIL_TIME=$(tail -1 /tmp/install-*.log | cut -d']' -f1 | cut -d'[' -f2)
echo "Start: $HEAD_TIME"
echo "End: $TAIL_TIME"

Common Log Patterns

Successful Installation

⏳ Creating LXC container
✔ Created LXC container (107)
⏳ Starting LXC container
✔ Started LXC container
⏳ Setting up Container OS
✔ Set up Container OS
⏳ Updating Container OS
✔ Updated Container OS
⏳ Installing Dependencies
✔ Installed Dependencies
...
✔ Completed Successfully!

Failed Installation

⏳ Installing Dependencies
[ERROR] in line 156: exit code 100 (APT: Package manager error)
while executing command apt-get install -y curl wget
--- Last 20 lines of log ---
...
E: Unable to fetch some archives

Network Issues

⏳ Downloading template
[ERROR] in line 89: exit code 222 (Template download failed)
while executing command pveam download local debian-13-standard
--- Last 20 lines of log ---
...
failed to download template
no route to host

Permission Issues

⏳ Creating directories
[ERROR] in line 203: exit code 1 (General error / Operation not permitted)
while executing command mkdir -p /opt/app
--- Last 20 lines of log ---
...
mkdir: cannot create directory '/opt/app': Permission denied

Log Retention and Cleanup

Automatic Cleanup

Temporary Logs (/tmp/):

Automatically cleaned on system reboot
Removed after successful installation (installation logs only)
Preserved on failure for debugging

Persistent Logs (/var/log/community-scripts/):

Never automatically deleted
Must be manually cleaned or archived

Manual Cleanup

# Remove logs older than 7 days
find /tmp -name "create-lxc-*.log" -mtime +7 -delete
find /tmp -name "install-lxc-*.log" -mtime +7 -delete

Advanced Log Features

Trace Mode Logs

When using dev_mode="trace", logs include bash execution traces:

+(/opt/app/install.sh): cd /opt/app
+(/opt/app/install.sh): curl -sL https://example.com/app.tar.gz
+(/opt/app/install.sh): tar xzf app.tar.gz
+(/opt/app/install.sh): ./configure --prefix=/usr/local
+(/opt/app/install.sh): make
+(/opt/app/install.sh): make install

Find trace entries:

# Extract only trace lines
grep "^+" /var/log/community-scripts/install-*.log

# Find specific command traces
grep "^+.*curl" /var/log/community-scripts/install-*.log

Trace logs may contain sensitive information like passwords. Handle with care.

Session Correlation

Each installation has a unique SESSION_ID that links creation and installation logs:

# Find session ID from creation log
SESSION_ID=$(grep -oP 'SESSION_ID=\K[a-z0-9]+' /tmp/create-lxc-*.log | head -1)

# Find all logs for this session
grep -l "$SESSION_ID" /var/log/community-scripts/*.log

# View complete session timeline
grep "$SESSION_ID" /var/log/community-scripts/*.log | sort

Exporting Logs for Support

Creating Debug Packages

# Collect all relevant logs and system info
export dev_mode="logs"
bash -c "$(curl ...)"

# After failure, create debug package
DEBUG_PKG="debug-$(date +%Y%m%d-%H%M%S).tar.gz"
tar czf "$DEBUG_PKG" \
  /var/log/community-scripts/ \
  /tmp/create-lxc-*.log \
  /tmp/install-*.log \
  /etc/pve/lxc/<CTID>.conf

# Include system info
pvecm status > /tmp/cluster-status.txt 2>&1
pvesm status > /tmp/storage-status.txt 2>&1
pveversion > /tmp/pve-version.txt 2>&1

tar czf "$DEBUG_PKG" --append \
  /tmp/cluster-status.txt \
  /tmp/storage-status.txt \
  /tmp/pve-version.txt

echo "Debug package created: $DEBUG_PKG"

Sanitizing Logs

Before sharing logs, remove sensitive information:

# Create sanitized copy
cp /tmp/install-lxc-107-abc.log /tmp/install-sanitized.log

# Remove passwords (basic pattern)
sed -i 's/password=[^ ]*/password=REDACTED/g' /tmp/install-sanitized.log
sed -i 's/PASSWORD=[^ ]*/PASSWORD=REDACTED/g' /tmp/install-sanitized.log

# Remove IP addresses (optional)
sed -i 's/[0-9]\{1,3\}\.[0-9]\{1,3\}\.[0-9]\{1,3\}\.[0-9]\{1,3\}/X.X.X.X/g' /tmp/install-sanitized.log

# Remove hostnames (optional)
sed -i 's/host=[^ ]*/host=REDACTED/g' /tmp/install-sanitized.log

Always review sanitized logs manually before sharing. Automated sanitization may miss sensitive data.

Best Practices

During Development

Always enable persistent logs:
```
export dev_mode="logs"
```
Use verbose mode for detailed output:
```
export var_verbose="yes"
```

Monitor logs in real-time:

tail -f /var/log/community-scripts/*.log

For Production

Keep creation logs for audit trail
Archive logs monthly
Monitor log disk usage
Set up log rotation if needed

For Troubleshooting

Check exit codes first - See Exit Codes
Read last 50 lines of logs - Most errors appear at the end
Search for “ERROR” and “exit code” - Quickly find failures
Enable trace mode for deep debugging - See Debug Mode
Correlate creation and installation logs - Use SESSION_ID

Getting Started

Core Concepts

Using Scripts

Configuration

Guides

Troubleshooting

Overview

Log File Locations

Default Log Locations (Without Debug Mode)

Persistent Logs (With Debug Mode)

Log Types and Contents

Creation Log (create-lxc-*.log)

Installation Log (install-*.log)

Error Log Entries

Reading and Analyzing Logs

Real-Time Monitoring

Searching Logs

Log Analysis Commands

Common Log Patterns

Successful Installation

Failed Installation

Network Issues

Permission Issues

Log Retention and Cleanup

Automatic Cleanup

Manual Cleanup

Advanced Log Features

Trace Mode Logs

Session Correlation

Exporting Logs for Support

Creating Debug Packages

Sanitizing Logs

Best Practices

During Development

For Production

For Troubleshooting

See Also

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Using Scripts

Configuration

Guides

Troubleshooting

​Overview

​Log File Locations

​Default Log Locations (Without Debug Mode)

​Persistent Logs (With Debug Mode)

​Log Types and Contents

​Creation Log (create-lxc-*.log)

​Installation Log (install-*.log)

​Error Log Entries

​Reading and Analyzing Logs

​Real-Time Monitoring

​Searching Logs

​Log Analysis Commands

​Common Log Patterns

​Successful Installation

​Failed Installation

​Network Issues

​Permission Issues

​Log Retention and Cleanup

​Automatic Cleanup

​Manual Cleanup

​Advanced Log Features

​Trace Mode Logs

​Session Correlation

​Exporting Logs for Support

​Creating Debug Packages

​Sanitizing Logs

​Best Practices

​During Development

​For Production

​For Troubleshooting

​See Also

Build docs developers (and LLMs) love

Overview

Log File Locations

Default Log Locations (Without Debug Mode)

Persistent Logs (With Debug Mode)

Log Types and Contents

Creation Log (create-lxc-*.log)

Installation Log (install-*.log)

Error Log Entries

Reading and Analyzing Logs

Real-Time Monitoring

Searching Logs

Log Analysis Commands

Common Log Patterns

Successful Installation

Failed Installation

Network Issues

Permission Issues

Log Retention and Cleanup

Automatic Cleanup

Manual Cleanup

Advanced Log Features

Trace Mode Logs

Session Correlation

Exporting Logs for Support

Creating Debug Packages

Sanitizing Logs

Best Practices

During Development

For Production

For Troubleshooting

See Also