Custodian Service Documentation

Overview

Custodian Service is a Windows service application that automatically manages file cleanup, archiving, and compression based on file age and configurable rules. The service runs in the background and can monitor multiple folders simultaneously with different processing rules for each.

Features

• Automatic File Management: Monitors folders and processes files based on age thresholds
• Multiple Processing Modes:
• Delete: Permanently removes old files
• Archive: Moves or copies files to archive location
• Zip: Compresses files into ZIP archives
• Flexible Scheduling: Configure different check intervals for each folder
• File Filtering: Use wildcard patterns to target specific file types
• Service Control: Supports standard Windows service operations (Start, Stop, Pause, Resume)
• Detailed Logging: Tracks all operations for auditing and troubleshooting

---

Installation

Prerequisites

• Windows operating system (Windows 7/Server 2008 R2 or later)
• Administrator privileges for installation

Installation Steps

1. Copy Files
2. Copy Custodian.exe to your desired installation directory

3. Example: C:\Program Files\CustodianService\

4. Create Configuration File

5. Create config.ini in the same directory as the executable

6. See Configuration section for details

7. Install the Service (as Administrator) cmd cd "C:\Program Files\CustodianService" Custodian.exe /install

8. Set Service Description (optional) cmd sc description CustodianService "Automatically manages file cleanup, archiving, and compression based on age and configuration rules"

9. Start the Service cmd net start CustodianService

Or use Services console (services.msc):

• Find "Custodian Service"
• Right-click → Start

Uninstallation

1. Stop the Service cmd net stop CustodianService

2. Uninstall the Service cmd Custodian.exe /uninstall

3. Remove Files

4. Delete the installation directory

---

Configuration

The service is configured using config.ini file located in the same directory as the executable.

Configuration Parameters

Required Parameters

Parameter	Description	Example
Path	Folder path to monitor	C:\Temp
Days	Age threshold in days	30
Mode	Processing mode: Delete, Archive, or Zip	Delete
IntervalMinutes	Check interval in minutes	60

Optional Parameters

Parameter	Description	Default	Example
ArchivePath	Destination for Archive/Zip mode	N/A	D:\Archive
KeepOriginal	Keep original files (true/false)	false	true
Mask1, Mask2, ...	File patterns to match	All files	*.log

Processing Modes

Delete Mode

Permanently deletes files older than the specified threshold.

[Folder1]
Path=C:\Temp
Days=7
Mode=Delete
IntervalMinutes=60
Mask1=*.tmp
Mask2=*.cache

Behavior:

• Files matching the masks and older than 7 days are deleted
• No archive path needed
• Files are permanently removed

Archive Mode

Moves or copies files to an archive location.

[Folder2]
Path=C:\Production\Logs
Days=30
Mode=Archive
ArchivePath=D:\Archive\Logs
IntervalMinutes=360
KeepOriginal=false
Mask1=*.log

Behavior:

• KeepOriginal=false: Files are moved to ArchivePath (original deleted)
• KeepOriginal=true: Files are copied to ArchivePath (original kept)
• Original filename is preserved
• Archive folder is created automatically if it doesn't exist

Zip Mode

Compresses files into a ZIP archive.

[Folder3]
Path=C:\Backups
Days=90
Mode=Zip
ArchivePath=D:\Archive\backups.zip
IntervalMinutes=1440
KeepOriginal=false
Mask1=*.bak
Mask2=*.sql

Behavior:

• Files are added to the specified ZIP file
• KeepOriginal=false: Original files are deleted after compression
• KeepOriginal=true: Original files remain after compression
• ZIP file is created automatically if it doesn't exist
• Files are appended to existing ZIP

File Masks (Wildcard Patterns)

Masks use Windows wildcard patterns to filter files:

Pattern	Matches	Example
*.log	All .log files	error.log, app.log
*.tmp	All .tmp files	cache.tmp, temp.tmp
test*.*	Files starting with "test"	test1.txt, test_data.csv
~*.*	Files starting with ~	~tempfile.doc
2024*.log	Log files starting with 2024	20240115.log
(no masks)	All files	Everything in folder

Multiple Masks:

Mask1=*.log
Mask2=*.txt
Mask3=*.bak
Mask4=*.tmp

Files matching any mask will be processed.

Common Interval Settings

Frequency	Minutes	Use Case
Every hour	60	Temporary files
Every 6 hours	360	Application logs
Daily (midnight)	1440	Daily backups
Weekly	10080	Archive operations
Monthly	43200	Long-term cleanup

Multiple Folder Monitoring

Monitor multiple folders by creating additional sections:

[Folder1]
Path=C:\Temp
Days=7
Mode=Delete
IntervalMinutes=60

[Folder2]
Path=C:\Logs
Days=30
Mode=Archive
ArchivePath=D:\Archive\Logs
IntervalMinutes=360

[Folder3]
Path=C:\Backups
Days=90
Mode=Zip
ArchivePath=D:\Archive\backups.zip
IntervalMinutes=1440

Important: Each folder section must start with [Folder (case-insensitive). Example: [Folder1], [Folder2], [FolderTemp], [FolderLogs]

---

Operation

Service Lifecycle

1. Service Start
2. Reads config.ini
3. Initializes folder monitoring
4. Schedules first check to run immediately

5. Logs startup information

6. During Operation

7. Monitors folders based on configured intervals
8. Processes files matching age and mask criteria
9. Logs all operations

10. Responds to service control commands

11. Service Stop

12. Completes current folder processing (if any)
13. Logs shutdown
14. Cleanly terminates

Service Control

Using Command Line

rem Start service
net start CustodianService

rem Stop service
net stop CustodianService

rem Pause service
net pause CustodianService

rem Resume service
net continue CustodianService

rem Check service status
sc query CustodianService

Using Services Console

1. Press Win + R, type services.msc, press Enter
2. Find "Custodian Service" in the list
3. Right-click for options:
4. Start
5. Stop
6. Pause
7. Resume
8. Restart

Service Properties

In Services console, right-click → Properties:

• Startup Type:
• Automatic: Starts with Windows
• Manual: Start manually when needed

• Disabled: Prevents service from starting

• Log On tab:

• Default: Local System (recommended for full access)
• Custom account: If specific permissions needed

---

Logging

Log File Location

Logs are written to: service.log in the same directory as the executable.

Example: C:\Program Files\CustodianService\service.log

Log Entries

The service logs all significant operations:

Service Events:

1/15/2026 10:00:00 AM Service started
1/15/2026 10:00:00 AM Service directory: C:\Program Files\CustodianService\
1/15/2026 10:00:00 AM Processing folder: C:\Temp
1/15/2026 2:30:45 PM Service paused
1/15/2026 2:35:12 PM Service resumed
1/15/2026 11:59:58 PM Service stopping

File Operations:

1/15/2026 10:05:23 AM Deleted: C:\Temp\oldfile.tmp
1/15/2026 10:05:24 AM Moved: C:\Logs\app.log -> D:\Archive\Logs
1/15/2026 10:05:25 AM Copied: C:\Data\report.pdf -> D:\Archive
1/15/2026 10:05:26 AM Zipped: C:\Backup\data.bak -> D:\Archive\backups.zip
1/15/2026 10:05:27 AM Zipped: C:\Backup\test.sql -> D:\Archive\backups.zip (kept original)

Errors:

1/15/2026 10:10:00 AM WARNING: Config file not found at C:\Program Files\CustodianService\config.ini
1/15/2026 10:15:32 AM Error processing folder C:\Temp: Access denied
1/15/2026 10:20:45 AM Error processing file C:\Temp\locked.tmp: The process cannot access the file because it is being used by another process

Log Management

The service does not automatically rotate or clean up log files. To manage log size:

1. Manual cleanup: Periodically delete or archive service.log
2. Automated cleanup: Use Windows Task Scheduler or another tool
3. Monitor size: Check log file size regularly

Example log cleanup script:

@echo off
rem Archive old log file
copy "C:\Program Files\CustodianService\service.log" "C:\Archive\service_%DATE%.log"
del "C:\Program Files\CustodianService\service.log"

---

Troubleshooting

Service Won't Start

Problem: Service fails to start or stops immediately

Solutions:

1. Check service.log for error messages
2. Verify config.ini exists in the same directory as the executable
3. Ensure paths in config.ini are valid
4. Verify service has necessary permissions (usually runs as Local System)
5. Check Windows Event Viewer → Windows Logs → Application

Files Not Being Processed

Problem: Files remain in monitored folders

Possible Causes:

1. Files not old enough: Check Days parameter
2. Mask mismatch: Files don't match any mask patterns
3. Service paused: Check service status
4. Interval not reached: Check IntervalMinutes and when service started
5. Permission issues: Service can't access files

Debugging Steps:

rem Check service status
sc query CustodianService

rem View recent log entries
type "C:\Program Files\CustodianService\service.log"

Configuration Not Loading

Problem: Changes to config.ini not taking effect

Solution: Restart the service

net stop CustodianService
net start CustodianService

Configuration is only read at service startup.

Access Denied Errors

Problem: Log shows "Access denied" errors

Solutions:

1. Verify service account has permissions to folders
2. Check if files are locked by other processes
3. Ensure archive destination is writable
4. Run service as Local System (default) or account with appropriate permissions

Service Won't Stop

Problem: Service hangs when stopping

Possible Causes:

1. Processing large number of files
2. Waiting for file operations to complete

Solutions:

1. Wait a few minutes for current operations to complete
2. If truly hung, use Task Manager to end process (not recommended)
3. Check service.log for last operation

---

Best Practices

Configuration

1. Start Conservative: Begin with longer intervals and higher day thresholds
2. Test First: Test configuration on non-critical folders before production
3. Use Specific Masks: Target specific file types rather than all files
4. Archive Before Delete: Consider archiving before switching to delete mode
5. Backup Config: Keep backup copy of config.ini

Monitoring

1. Review Logs Regularly: Check service.log weekly
2. Monitor Disk Space: Ensure archive destinations have adequate space
3. Test Recovery: Verify you can restore archived files if needed
4. Document Configuration: Keep notes on why each folder is configured

Security

1. Limit Permissions: Only grant necessary folder access
2. Secure Archive Location: Protect archive destinations
3. Audit Trails: Preserve logs for compliance/auditing
4. Test Restore: Regularly test file restoration from archives/ZIPs

Performance

1. Stagger Intervals: Don't schedule all folders at same time
2. Avoid Peak Hours: Schedule intensive operations during off-hours
3. Monitor Resources: Watch CPU/disk usage during operation
4. Limit File Count: Consider splitting large folders into multiple configurations

---

Example Configurations

Small Office - Basic Cleanup

[FolderTemp]
Path=C:\Windows\Temp
Days=7
Mode=Delete
IntervalMinutes=1440
Mask1=*.tmp
Mask2=*.temp

[FolderUserTemp]
Path=C:\Users\*\AppData\Local\Temp
Days=14
Mode=Delete
IntervalMinutes=1440

Application Server - Log Management

[FolderAppLogs]
Path=C:\ProgramData\MyApp\Logs
Days=30
Mode=Archive
ArchivePath=D:\Archive\AppLogs
IntervalMinutes=360
KeepOriginal=false
Mask1=*.log
Mask2=*.txt

[FolderWebLogs]
Path=C:\inetpub\logs
Days=90
Mode=Zip
ArchivePath=D:\Archive\WebLogs.zip
IntervalMinutes=1440
KeepOriginal=false
Mask1=*.log

Database Server - Backup Management

[FolderDailyBackups]
Path=C:\Backups\Daily
Days=7
Mode=Archive
ArchivePath=C:\Backups\Weekly
IntervalMinutes=1440
KeepOriginal=false
Mask1=*.bak

[FolderWeeklyBackups]
Path=C:\Backups\Weekly
Days=30
Mode=Zip
ArchivePath=D:\Archive\MonthlyBackups.zip
IntervalMinutes=10080
KeepOriginal=false
Mask1=*.bak

---

Technical Details

System Requirements

• OS: Windows 7 / Server 2008 R2 or later
• Permissions: Administrator for installation, Local System for operation
• Disk Space: Minimal (< 5 MB for executable)
• Memory: Minimal (< 10 MB typical usage)

File Processing Logic

1. Service checks each configured folder at its specified interval
2. For each file in the folder:
3. Skip if it's a directory
4. Skip if it doesn't match any mask (if masks specified)
5. Check if file age > Days threshold
6. If yes, process according to Mode
7. Log all operations
8. Schedule next check

Age Calculation

File age is calculated using the Last Write Time (modification date):

• Current time - Last Write Time > Days × 24 hours
• Uses system time (ensure system clock is correct)

Service Architecture

• Built using Borland C++ Builder VCL Framework
• Runs as Windows Service (SERVICE_WIN32_OWN_PROCESS)
• Single-threaded with event-based processing
• Uses high-resolution performance counters for scheduling
• Supports Pause/Resume operations

---

Support and Maintenance

Updating Configuration

1. Stop the service
2. Edit config.ini
3. Start the service

Changes take effect immediately on service start.

Updating the Service

1. Stop the service: net stop CustodianService
2. Replace executable with new version
3. Start the service: net start CustodianService

Backing Up

Files to backup:

• config.ini - Configuration
• service.log - Operation history (optional)

Recommended backup location: Outside the service directory

Last Updated: January 2026