File manager

? PNG %k25u25%fgd5n! File manager

File manager - Edit - /usr/local/cpanel/scripts/comet_protected_item_maintenance

Back
#!/usr/local/cpanel/3rdparty/bin/perl # Copyright 2025 WebPros International, LLC # All rights reserved. # copyright@cpanel.net http://cpanel.net # This code is subject to the cPanel license. Unauthorized copying is prohibited. =encoding utf-8 =head1 NAME comet_protected_item_maintenance - Maintenance and retention operations for Comet Protected Items and deleted users =head1 SYNOPSIS comet_protected_item_maintenance [--status] comet_protected_item_maintenance --list-users comet_protected_item_maintenance --prune-days=90 [--user=USERNAME] [--users=USER1,USER2,...] [--dry-run] comet_protected_item_maintenance --list-deleted-user-snapshots comet_protected_item_maintenance --prune-user=USERNAME [--dry-run] comet_protected_item_maintenance --prune-all-deleted-users [--dry-run] comet_protected_item_maintenance --restore-deleted-user=USERNAME [--use-snapshot=SNAPSHOT_ID] [--dry-run] =head1 DESCRIPTION Performs maintenance on the consolidated metadata database for Comet Protected Items and deleted cPanel users. Supports listing users, pruning terminated Protected Item records, pruning deleted user snapshot records from backup run logs, enumerating snapshots for deleted users, marking deleted users as pruned (stub), and simulating a restore (stub implementation). The metadata database tracks both active Protected Item mappings and retention information for deleted users. Snapshot data is stored in the backup run logs database. Actual snapshot and restore logic are pending integration with the backend Comet service; current commands provide placeholders to exercise CLI flows. =cut package scripts::comet_protected_item_maintenance; use cPstrict; use Getopt::Long (); use Pod::Usage (); use FindBin; use lib "$FindBin::Bin/../plugins/whm/comet/perl/usr/local/cpanel"; use Whostmgr::CometBackup::ProtectedItemMap (); use Whostmgr::CometBackup::DeletedUsers (); # Option variables my $prune_days = 0; my $list_users = 0; my $help = 0; my $status = 0; # explicit status request my $prune_user = ''; my $prune_all_deleted_users = 0; my $list_deleted_snapshots = 0; my $restore_deleted_user = ''; my $use_snapshot = ''; my $dry_run = 0; my $user = ''; # single user for --prune-days my $users = ''; # comma-separated users for --prune-days sub main { Getopt::Long::GetOptions( 'prune-days=i' => \$prune_days, 'list-users' => \$list_users, 'help\|h' => \$help, 'status' => \$status, 'prune-user=s' => \$prune_user, 'prune-all-deleted-users' => \$prune_all_deleted_users, 'list-deleted-user-snapshots' => \$list_deleted_snapshots, 'restore-deleted-user=s' => \$restore_deleted_user, 'use-snapshot=s' => \$use_snapshot, 'dry-run' => \$dry_run, 'user=s' => \$user, 'users=s' => \$users, ) or Pod::Usage::pod2usage(2); if ($help) { Pod::Usage::pod2usage(1); return; } my $map = Whostmgr::CometBackup::ProtectedItemMap->new(); my $deleted = Whostmgr::CometBackup::DeletedUsers->new(); # Dispatch precedence: prune specific user, prune all, restore, list snapshots, prune-days, list-users, status(default) if ($prune_user) { prune_single_deleted_user( $deleted, $prune_user, $dry_run ); return; } if ($prune_all_deleted_users) { prune_all_deleted_users( $deleted, $dry_run ); return; } if ($restore_deleted_user) { restore_deleted_user( $deleted, $restore_deleted_user, $use_snapshot, $dry_run ); return; } if ($list_deleted_snapshots) { list_deleted_user_snapshots($deleted); return; } if ($prune_days) { prune_old_records( $map, $prune_days, $dry_run, $user, $users ); return; } if ($list_users) { list_users_with_protected_items($map); return; } # Default status view show_status( $map, $deleted ); return; } sub show_status ( $map, $deleted ) { print "Comet Protected Item / Deleted User Status\n"; print "========================================\n\n"; my @all_users = $map->get_all_users_with_protected_items(); my @active_users = $map->get_all_users_with_protected_items( active_only => 1 ); my @deleted_users = $deleted->list_deleted_users(); print "Total users with protected items: " . scalar(@all_users) . "\n"; print "Users with active protected items: " . scalar(@active_users) . "\n"; print "Users with terminated items only: " . ( scalar(@all_users) - scalar(@active_users) ) . "\n"; # XXX: Delete this "Users with protected items" part? if (@all_users) { print "\nUsers with protected items:\n"; for my $user (@all_users) { my @items = $map->get_protected_items_for_user( system_user => $user ); my @active_items = grep { !$_->{user_terminated} } @items; my @terminated_items = grep { $_->{user_terminated} } @items; printf " %-20s: %d total (%d active, %d terminated)\n", $user, scalar(@items), scalar(@active_items), scalar(@terminated_items); } } print "Deleted users tracked: " . scalar(@deleted_users) . "\n"; print "\nUse --list-users for detailed information\n"; print "Use --prune-days=N to remove terminated Protected Item records\n"; print "Use --list-deleted-user-snapshots to view stub snapshots for deleted users\n"; print "Use --prune-user=USER or --prune-all-deleted-users to mark retained backups pruned (stub)\n"; print "Use --restore-deleted-user=USER [--use-snapshot=ID] to simulate restore (stub)\n"; return; } sub list_users_with_protected_items ($map) { print "Users with Protected Items\n"; print "==========================\n\n"; my @all_users = $map->get_all_users_with_protected_items( active_only => 1 ); if ( !@all_users ) { print "No users found with protected items.\n"; return; } for my $user (@all_users) { print "User: $user\n"; print "-" x 40 . "\n"; my @items = $map->get_protected_items_for_user( system_user => $user ); for my $item (@items) { my $user_status = $item->{user_terminated} ? 'Terminated' : 'Active'; my $item_status = $item->{status} \|\| 'unknown'; my $terminated = $item->{terminated_timestamp} ? localtime( $item->{terminated_timestamp} ) : 'N/A'; print " Protected Item: $item->{protected_item_uid}\n"; print " User Status: $user_status\n"; print " Item Status: $item_status\n"; print " User UUID: $item->{cpanel_user_uuid}\n"; print " Terminated: $terminated\n"; print "\n"; } } return; } sub prune_old_records ( $map, $days, $dry_run = 0, $single_user = '', $user_list = '' ) { my $cutoff_time = time() - ( $days * 24 * 60 * 60 ); # Build list of users to target my @target_users; if ($single_user) { push @target_users, $single_user; } if ($user_list) { push @target_users, split( /,/, $user_list ); } if ($dry_run) { if (@target_users) { print "[DRY RUN] Would prune terminated records older than $days days for users: " . join( ', ', @target_users ) . "...\n"; } else { print "[DRY RUN] Would prune terminated records older than $days days...\n"; } # Query what would be pruned from Protected Item map my %prune_args = ( older_than_days => $days, dry_run => 1 ); $prune_args{users} = \@target_users if @target_users; my $map_count = $map->prune_inactive_users(%prune_args); print "[DRY RUN] Would prune $map_count old terminated Protected Item records.\n"; # Query what would be pruned from backup run logs (deleted user snapshots) my $deleted = Whostmgr::CometBackup::DeletedUsers->new(); my %snapshot_args = ( cutoff_epoch => $cutoff_time, dry_run => 1 ); $snapshot_args{users} = \@target_users if @target_users; my $result = $deleted->prune_deleted_user_snapshots_before(%snapshot_args); if ( $result->{error} ) { print "[DRY RUN] Error checking deleted user snapshots: $result->{error}\n"; } else { my $snapshot_count = $result->{count}; my @affected_users = @{ $result->{users_affected} \|\| [] }; print "[DRY RUN] Would prune $snapshot_count deleted user snapshot records"; if (@affected_users) { print " for users: " . join( ', ', @affected_users ); } print ".\n"; } my $total = $map_count + ( $result->{count} \|\| 0 ); print "[DRY RUN] Total records that would be pruned: $total\n"; } else { if (@target_users) { print "Pruning terminated records older than $days days for users: " . join( ', ', @target_users ) . "...\n"; } else { print "Pruning terminated records older than $days days...\n"; } # Prune terminated Protected Item records my %prune_args = ( older_than_days => $days ); $prune_args{users} = \@target_users if @target_users; my $map_count = $map->prune_inactive_users(%prune_args); print "Pruned $map_count old terminated Protected Item records.\n"; # Prune deleted user snapshots from backup run logs my $deleted = Whostmgr::CometBackup::DeletedUsers->new(); my %snapshot_args = ( cutoff_epoch => $cutoff_time, dry_run => 0 ); $snapshot_args{users} = \@target_users if @target_users; my $result = $deleted->prune_deleted_user_snapshots_before(%snapshot_args); if ( $result->{error} ) { print "Error pruning deleted user snapshots: $result->{error}\n"; } else { my $snapshot_count = $result->{count}; my @affected_users = @{ $result->{users_affected} \|\| [] }; print "Pruned $snapshot_count deleted user snapshot records"; if (@affected_users) { print " for users: " . join( ', ', @affected_users ); } print ".\n"; } my $total = $map_count + ( $result->{count} \|\| 0 ); print "Total records pruned: $total\n"; } } sub list_deleted_user_snapshots ($deleted) { my @users = $deleted->list_deleted_users(); if ( !@users ) { print "No deleted users to list snapshots for.\n"; return; } # Filter to only include users that don't exist locally anymore my @truly_deleted_users = grep { my $username = $_->{system_user}; !getpwnam($username); # Only include if user doesn't exist } @users; if ( !@truly_deleted_users ) { print "No deleted users to list snapshots for.\n"; print "(All tracked deleted users still exist in the system)\n"; return; } print "Deleted User Snapshots\n"; print "======================\n\n"; for my $user_info (@truly_deleted_users) { my $username = $user_info->{system_user}; my $result = $deleted->list_deleted_user_snapshots($username); if ( $result->{error} ) { print "Error for user $username: $result->{error}\n\n"; next; } print "User: $username\n"; print "-" x ( 6 + length($username) ) . "\n"; if ( $result->{count} == 0 ) { print " No snapshots available\n\n"; next; } for my $snap ( @{ $result->{snapshots} } ) { my $created = localtime( $snap->{created_at} // time() ); my $size = $snap->{size} // 'Unknown'; my $type = $snap->{type} // 'Unknown'; my $status = $snap->{status} // 'Unknown'; my $source_id = $snap->{source_id} // $snap->{protected_item_id} // 'Unknown'; my $destination_id = $snap->{destination_id} // 'Unknown'; my $snapshot_id = $snap->{snapshot_uuid} // $snap->{snapshot_id} // 'Unknown'; print " Snapshot:\n"; print " Source ID: $source_id\n"; print " Destination ID: $destination_id\n"; print " Snapshot ID: $snapshot_id\n"; print " Type: $type\n"; print " Created: $created\n"; print " Size: $size bytes\n"; print " Status: $status\n"; print "\n"; } print "\n"; } return; } sub prune_single_deleted_user ( $deleted, $user, $dry_run = 0 ) { if ($dry_run) { print "[DRY RUN] Would prune deleted user '$user'...\n"; my $result = $deleted->prune_single_deleted_user( $user, dry_run => 1 ); if ( $result->{error} ) { print "[DRY RUN] Error: $result->{error}\n"; return; } print "[DRY RUN] Would succeed: $result->{message}\n"; } else { print "Pruning deleted user '$user'...\n"; my $result = $deleted->prune_single_deleted_user($user); if ( $result->{error} ) { print "Error: $result->{error}\n"; return; } print "Success: $result->{message}\n"; } return; } sub prune_all_deleted_users ( $deleted, $dry_run = 0 ) { my @users = $deleted->list_deleted_users(); if ( !@users ) { print "No deleted users to prune.\n"; return; } if ($dry_run) { print "[DRY RUN] Would prune all " . scalar(@users) . " deleted users...\n"; } else { print "Pruning all " . scalar(@users) . " deleted users...\n"; } my $success_count = 0; my $error_count = 0; for my $user_info (@users) { my $username = $user_info->{system_user}; if ($dry_run) { print "[DRY RUN] Would prune user '$username'... "; my $result = $deleted->prune_single_deleted_user( $username, dry_run => 1 ); if ( $result->{error} ) { print "Error: $result->{error}\n"; $error_count++; } else { print "Success\n"; $success_count++; } } else { print "Pruning user '$username'... "; my $result = $deleted->prune_single_deleted_user($username); if ( $result->{error} ) { print "Error: $result->{error}\n"; $error_count++; } else { print "Success\n"; $success_count++; } } } if ($dry_run) { print "\n[DRY RUN] Pruning complete: $success_count would succeed, $error_count errors\n"; } else { print "\nPruning complete: $success_count successful, $error_count errors\n"; } return; } sub restore_deleted_user ( $deleted, $user, $snapshot, $dry_run = 0 ) { if ( !$snapshot ) { # Auto-select latest snapshot if not specified my $snapshots_result = $deleted->list_deleted_user_snapshots($user); if ( $snapshots_result->{error} ) { print "Error: Failed to list snapshots for user '$user': $snapshots_result->{error}\n"; return; } if ( !$snapshots_result->{snapshots} \|\| @{ $snapshots_result->{snapshots} } == 0 ) { print "Error: No snapshots available for user '$user'\n"; return; } # Sort snapshots by created_at descending to get the latest one my @sorted_snapshots = sort { ( $b->{created_at} // 0 ) <=> ( $a->{created_at} // 0 ) } @{ $snapshots_result->{snapshots} }; # Use the latest snapshot (first after sorting) $snapshot = $sorted_snapshots[0]->{snapshot_uuid} // $sorted_snapshots[0]->{snapshot_id}; if ( !$snapshot ) { print "Error: Could not determine snapshot identifier for user '$user'\n"; return; } print "Using latest snapshot: $snapshot\n"; } if ($dry_run) { print "[DRY RUN] Would restore deleted user '$user' from snapshot '$snapshot'...\n"; my $result = $deleted->restore_deleted_user( $user, $snapshot, dry_run => 1 ); if ( $result->{error} ) { print "[DRY RUN] Error: $result->{error}\n"; return; } print "[DRY RUN] Would succeed: $result->{message}\n"; if ( $result->{job_uuid} ) { print "[DRY RUN] Would create restore job UUID: $result->{job_uuid}\n"; } } else { print "Restoring deleted user '$user' from snapshot '$snapshot'...\n"; my $result = $deleted->restore_deleted_user( $user, $snapshot ); if ( $result->{error} ) { print "Error: $result->{error}\n"; return; } print "Success: $result->{message}\n"; if ( $result->{job_uuid} ) { print "Restore job UUID: $result->{job_uuid}\n"; } } return; } # Run as script if not required as module main() if !caller(); 1; __END__ =head1 OPTIONS =over 4 =item B<--status> Show aggregate status (default when no other option is provided). =item B<--list-users> List all users with their Protected Items and activity status. =item B<--prune-days=N> Remove terminated Protected Item records and deleted user snapshot records older than N days. This prunes both the Protected Item map entries for terminated users and the actual snapshot records from the backup run logs database. =item B<--user=USERNAME> Limit --prune-days to a specific user. Can be used multiple times or combined with --users to target multiple users. =item B<--users=USER1,USER2,...> Limit --prune-days to a comma-separated list of users. Can be combined with --user to target additional users. =item B<--list-deleted-user-snapshots> List stub snapshot identifiers for all deleted users. =item B<--prune-user=USERNAME> Mark retained backups for a specific deleted user as pruned (stub implementation). =item B<--prune-all-deleted-users> Mark retained backups for all deleted users as pruned (stub implementation). =item B<--restore-deleted-user=USERNAME> Simulate a restore of a deleted user (stub). If --use-snapshot is not provided, the most recent snapshot will be automatically selected based on creation timestamp. =item B<--use-snapshot=SNAPSHOT_ID> Specify snapshot identifier for simulated restore (used with --restore-deleted-user). If not specified, the most recent snapshot will be used automatically. =item B<--dry-run> Perform a dry run without making any actual changes. Shows what would be done without modifying the database or performing actual operations. Can be used with --prune-days, --prune-user, --prune-all-deleted-users, and --restore-deleted-user. =item B<--help> Show help message. =back =head1 EXAMPLES Show current status: comet_protected_item_maintenance --status List all users and their protected items: comet_protected_item_maintenance --list-users Remove terminated records older than 90 days: comet_protected_item_maintenance --prune-days=90 Remove terminated records for a specific user: comet_protected_item_maintenance --prune-days=90 --user=alice Remove terminated records for multiple users: comet_protected_item_maintenance --prune-days=90 --users=alice,bob,charlie List deleted user snapshots (stub): comet_protected_item_maintenance --list-deleted-user-snapshots Prune a single deleted user: comet_protected_item_maintenance --prune-user=alice Restore a deleted user using the most recent snapshot (stub): comet_protected_item_maintenance --restore-deleted-user=alice Restore a deleted user using a specific snapshot (stub): comet_protected_item_maintenance --restore-deleted-user=alice --use-snapshot=alice-snapA Perform a dry run to see what would be pruned without making changes: comet_protected_item_maintenance --prune-days=90 --dry-run comet_protected_item_maintenance --prune-user=alice --dry-run comet_protected_item_maintenance --prune-all-deleted-users --dry-run comet_protected_item_maintenance --restore-deleted-user=alice --dry-run =head1 FILES =over 4 =item F</var/cpanel/comet/usermap.db> SQLite database containing Protected Item mappings and deleted user retention metadata. =item F</var/cpanel/comet/backup_run_logs.db> SQLite database containing backup run logs and snapshot records for all users, including deleted users. Pruned by the --prune-days option. =back =cut