Jenkins Backup and Restoration Guide

jenkins_backup_restore.md

Jenkins Backup and Restoration Guide

This guide provides detailed instructions for backing up and restoring Jenkins configurations, jobs, and credentials when running Jenkins via WAR file.

Current Setup

System Information

• Jenkins running from WAR file
• Jenkins home directory: /data/jenkins
• WAR file: jenkins_2.452.1.war
• Running on port 9000
• Essential plugins installed:
  • SSH
  • SSH Agent
  • Subversion
  • Maven Integration
  • Eclipse Temurin installer
  • Config File Provider
  • Pipeline Maven Integration
  • SonarQube Scanner
  • Docker
  • Docker Pipeline
  • Kubernetes Client API
  • Kubernetes Credentials
  • Kubernetes
  • Kubernetes CLI

Backup Process

1. Backup Script

Create a file named jenkins_backup.sh:

#!/bin/bash

# Jenkins directory
JENKINS_HOME="/data/jenkins"

# Backup destination
BACKUP_DIR="/data/jenkins_backups"
BACKUP_NAME="jenkins_backup_$(date +%Y%m%d_%H%M%S)"

# Create backup directory if it doesn't exist
mkdir -p "$BACKUP_DIR"

# Create backup without stopping Jenkins
echo "Creating backup..."
tar -czf "$BACKUP_DIR/$BACKUP_NAME.tar.gz" \
    -C $(dirname "$JENKINS_HOME") \
    --exclude="jenkins/war" \
    --exclude="jenkins/cache" \
    --exclude="jenkins/logs" \
    --exclude="jenkins/workspace" \
    $(basename "$JENKINS_HOME")

# Cleanup old backups (keep last 5)
cd "$BACKUP_DIR"
ls -t | grep 'jenkins_backup_.*\.tar\.gz$' | tail -n +6 | xargs -r rm

echo "Backup completed: $BACKUP_DIR/$BACKUP_NAME.tar.gz"

2. Setting Up Automated Backups

1. Save the script and make it executable:

chmod +x /data/jenkins/jenkins_backup.sh

2. Test the backup script:

./jenkins_backup.sh

3. Set up daily backup at 2 AM using cron:

crontab -e

# Add this line:
0 2 * * * /data/jenkins/jenkins_backup.sh

3. What Gets Backed Up

• Job configurations (jobs directory)
• Credentials (credentials.xml and secrets directory)
• Plugin configurations (various .xml files)
• User configurations (users directory)
• Global configurations (config.xml)

4. What's Excluded

• Workspace directory
• Build artifacts
• Cache files
• Log files
• WAR file

Restoration Process

1. Prerequisites

• Ensure you have the Jenkins WAR file ready
• Sufficient disk space (check with df -h)
• Note the current Jenkins port and any custom parameters

2. Restoration Steps

# 1. Stop Jenkins if running
pid=$(pgrep -f jenkins.war)
if [ ! -z "$pid" ]; then
    kill $pid
    sleep 10
fi

# 2. Create a backup of current state (just in case)
cd /data/jenkins
tar -czf ../jenkins_pre_restore_$(date +%Y%m%d_%H%M%S).tar.gz ./*

# 3. Clear current Jenkins directory (except the WAR file and backup script)
mv jenkins_2.452.1.war ../
mv jenkins_backup.sh ../
rm -rf ./*

# 4. Extract backup
tar -xzf /data/jenkins_backups/jenkins_backup_YYYYMMDD_HHMMSS.tar.gz -C /data/jenkins/

# 5. Move WAR and backup script back
mv ../jenkins_2.452.1.war .
mv ../jenkins_backup.sh .

# 6. Start Jenkins
nohup java -jar jenkins_2.452.1.war --httpPort=9000 > nohup.out 2>&1 &

# 7. Check logs
tail -f nohup.out

3. Post-Restoration Checklist

1. Verify Jenkins is running:

   • Access Jenkins web interface
   • Check system logs for errors

2. Verify configurations:

   • Test a few pipelines
   • Check if credentials are intact
   • Verify plugin functionality
   • Check global tool configurations

3. Common Issues and Solutions:

   • Missing plugins:
     • Go to "Manage Jenkins" → "Manage Plugins" → "Advanced" → "Check Now"
   • Missing credentials:
     • Verify both credentials.xml and secrets directory were restored
   • Failed builds:
     • Review global tool configurations
     • Check plugin configurations

Maintenance

1. Monitor Backup Sizes

# Check backup sizes
du -sh /data/jenkins_backups/*

# Check available space
df -h /data

2. Plugin Management

# Export list of installed plugins
java -jar jenkins-cli.jar -s http://localhost:9000/ list-plugins > plugins.txt

3. Best Practices

• Keep multiple backup copies
• Test restoration process periodically
• Document any custom configurations
• Monitor backup success/failures
• Clean up old workspaces regularly
• Maintain a list of installed plugins

Important Notes

1. Disk Space:

   • Ensure sufficient space in /data partition
   • Monitor backup sizes
   • Implement backup rotation (currently keeping last 5)

2. Security:

   • Backup files contain sensitive information
   • Secure backup location
   • Restrict access to backup files

3. Documentation:

   • Keep track of Jenkins version
   • Document custom configurations
   • Maintain list of critical jobs
   • Document any special plugin configurations