uscheduler/examples/File-Sync

File Sync Script

Version: 1.0.1 Last Updated: 2026-01-26

Overview

Production-ready automated file synchronization solution using FreeFileSync with scheduling, secure credential management, and remote storage support.

Features

• ✅ Automated File Sync - Executes FreeFileSync batch jobs on schedule
• ✅ Flexible Scheduling - Schedule sync by month, weekday, and time with interval control
• ✅ Remote Storage Support - Sync to UNC shares with secure credential management
• ✅ Prerequisite Validation - Checks FreeFileSync installation before execution
• ✅ Process Management - Proper cleanup of FreeFileSync process on exit
• ✅ Detailed Logging - Comprehensive logging with timestamps and severity levels
• ✅ Lock Files - Prevents concurrent execution
• ✅ Error Handling - Proper exit codes and error reporting

Requirements

System Requirements

• Windows with PowerShell 5.1 or later
• FreeFileSync installed (free download from https://freefilesync.org/)
• Network access to target share (if using UNC paths)

Dependencies

• SchedulerTemplate.psm1 module (located in parent directory)
• scriptsettings.json configuration file
• sync.ffs_batch FreeFileSync batch configuration file

File Structure

File-Sync/
├── file-sync.bat              # Batch launcher with admin check
├── file-sync.ps1              # Main PowerShell script
├── scriptsettings.json        # Configuration file
├── sync.ffs_batch             # FreeFileSync batch configuration
└── README.md                  # This file

Installation

1. Install FreeFileSync

   Download and install from https://freefilesync.org/

   Default installation path: C:\Program Files\FreeFileSync\FreeFileSync.exe

2. Copy Files

   # Copy the entire File-Sync folder to your desired location
   # Ensure SchedulerTemplate.psm1 is in the parent directory
   

3. Create FreeFileSync Batch Configuration

   Use FreeFileSync GUI to:

   • Configure source and destination folders
   • Set synchronization settings (Mirror, Two-way, Update, etc.)
   • Save as batch job: sync.ffs_batch in the File-Sync directory

4. Configure Settings

   Edit scriptsettings.json with your environment settings:

   {
     "schedule": {
       "runMonth": [],
       "runWeekday": ["Monday"],
       "runTime": ["00:00"],
       "minIntervalMinutes": 10
     },
     "freeFileSyncExe": "C:\\Program Files\\FreeFileSync\\FreeFileSync.exe",
     "batchFile": "sync.ffs_batch",
     "nasRootShare": "\\\\your-nas\\share",
     "credentialEnvVar": "YOUR_ENV_VAR_NAME"
   }
   

5. Setup Credentials (for UNC paths)

   If syncing to a network share, create a Machine-level environment variable:

   # Create Base64-encoded credentials
   $username = "DOMAIN\user"
   $password = "your-password"
   $creds = "$username:$password"
   $encoded = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($creds))
   
   # Set Machine-level environment variable
   [System.Environment]::SetEnvironmentVariable("YOUR_ENV_VAR_NAME", $encoded, "Machine")
   

6. Test Manual Execution

   # Run as Administrator
   .\file-sync.bat
   # or
   .\file-sync.ps1
   

Configuration Reference

Schedule Settings

Property	Type	Description	Example
runMonth	array	Month names to run. Empty = every month	["January", "June", "December"] or []
runWeekday	array	Weekday names to run. Empty = every day	["Monday", "Friday"]
runTime	array	UTC times to run (HH:mm format)	["00:00", "12:00"]
minIntervalMinutes	number	Minimum minutes between runs	10

Sync Settings

Property	Type	Required	Description
freeFileSyncExe	string	Yes	Full path to FreeFileSync.exe executable
batchFile	string	Yes	FreeFileSync batch file name (must be in same directory). Configure all sync paths directly in this file.
nasRootShare	string	Yes	UNC path to NAS root share for authentication only
credentialEnvVar	string	No*	Name of Machine-level environment variable with credentials (*Required for UNC paths)

Version Tracking

Property	Type	Description
version	string	Configuration schema version
lastModified	string	Last modification date (YYYY-MM-DD)

Usage

Manual Execution

Using Batch File (Recommended):

REM Right-click and select "Run as administrator"
file-sync.bat

Using PowerShell:

# Run as Administrator
.\file-sync.ps1

# With verbose output
.\file-sync.ps1 -Verbose

Automated Execution

The script supports automated execution through the UScheduler service:

# Called by scheduler with -Automated flag
.\file-sync.ps1 -Automated -CurrentDateTimeUtc "2026-01-24 00:00:00"

When -Automated is specified:

• Schedule is enforced (month, weekday, time)
• Lock files prevent concurrent execution
• Interval checking prevents duplicate runs
• Logs are formatted for service logger (no timestamps)

How It Works

Sync Process Flow

1. Initialization

   • Load SchedulerTemplate.psm1 module
   • Load and validate scriptsettings.json
   • Validate required settings
   • Construct batch file path

2. Pre-flight Checks

   • Verify FreeFileSync executable exists
   • Check FreeFileSync version
   • Verify batch configuration file exists
   • Authenticate to NAS share (if UNC)
   • Verify NAS reachability

3. Sync Execution

   • Launch FreeFileSync in silent mode
   • Capture stdout and stderr
   • Monitor process completion
   • Interpret exit code

4. Cleanup

   • Terminate FreeFileSync if script exits
   • Display sync summary

FreeFileSync Exit Codes

Code	Meaning	Script Action
0	Success	Mark as successful, exit 0
1	Warning (sync completed with warnings)	Mark as successful, exit 0
2	Error	Mark as failed, exit 1
3	Cancelled	Mark as failed, exit 1

Lock and State Files

When running in automated mode, the script creates:

• file-sync.lock - Prevents concurrent execution
• file-sync.lastRun - Tracks last execution time for interval control

Logging

Log Levels

Level	Description	Color (Manual)
Info	Informational messages	White
Success	Successful operations	Green
Warning	Non-critical issues	Yellow
Error	Critical errors	Red

Log Format

Manual Execution:

[2026-01-24 00:00:00] [Info] FreeFileSync Process Started
[2026-01-24 00:00:01] [Success] All prerequisites passed
[2026-01-24 00:05:30] [Success] FreeFileSync completed successfully

Automated Execution:

[Info] FreeFileSync Process Started
[Success] All prerequisites passed
[Success] FreeFileSync completed successfully

Exit Codes

Code	Description
0	Success (including warnings)
1	Error occurred (module load, config, prerequisites, sync failure)

Troubleshooting

Common Issues

1. Module Not Found

Error: Failed to load SchedulerTemplate.psm1

Solution: Ensure SchedulerTemplate.psm1 is in the parent directory (../SchedulerTemplate.psm1)

2. FreeFileSync Not Found

Error: FreeFileSync not found: C:\Program Files\FreeFileSync\FreeFileSync.exe

Solution:

• Install FreeFileSync from https://freefilesync.org/
• Update freeFileSyncExe path in scriptsettings.json if installed to custom location

3. Batch File Not Found

Error: Batch config not found

Solution:

• Create FreeFileSync batch configuration using FreeFileSync GUI
• Save as sync.ffs_batch in the File-Sync directory
• Update batchFile setting if using different name

4. UNC Path Authentication Failed

Error: Failed to connect to \\server\share

Solution:

• Verify credentialEnvVar is set in scriptsettings.json
• Verify environment variable exists at Machine level
• Verify credentials are Base64-encoded in format: username:password
• Test with: net use \\server\share manually

5. Lock File Exists

Guard: Lock file exists. Skipping.

Solution:

• Another instance is running, or previous run didn't complete
• Manually delete .lock file if stuck
• Check for hung PowerShell or FreeFileSync processes

6. FreeFileSync Errors

Error: FreeFileSync completed with errors (exit code 2)

Solution:

• Check FreeFileSync output in logs
• Verify source and destination paths are accessible
• Review FreeFileSync batch configuration
• Check file/folder permissions

Debug Mode

Run with verbose output:

.\file-sync.ps1 -Verbose

Best Practices

1. Test First - Always test sync manually before scheduling
2. Backup First - Ensure you have backups before first sync
3. Verify Paths - Double-check source and destination paths in batch file
4. Monitor Logs - Check sync summaries regularly
5. Secure Credentials - Use Machine-level environment variables, never store passwords in scripts
6. Schedule Wisely - Run syncs during low-usage periods
7. Review Settings - Understand FreeFileSync sync mode (Mirror, Two-way, Update)
8. Test Restores - Periodically verify you can restore from synced data

FreeFileSync Configuration

Creating Batch Configuration

1. Launch FreeFileSync GUI
2. Configure left (source) and right (target) folders
3. Set comparison settings (File time and size, Content, File size)
4. Set filter rules (include/exclude patterns)
5. Choose sync variant:
   • Mirror: Make right folder identical to left
   • Update: Copy new/updated files to right
   • Two-way: Propagate changes both ways
   • Custom: Define custom rules
6. Click "Save as batch job"
7. Save as sync.ffs_batch in File-Sync directory

Note: All source and destination paths are configured directly in the FreeFileSync batch file. The script does not modify these paths - it only handles authentication to network shares before FreeFileSync executes.

Security Considerations

• Credentials are stored Base64-encoded in Machine-level environment variables (not encryption, just encoding)
• Script requires Administrator privileges for network authentication
• Network credentials are passed to net use command
• Consider using dedicated sync account with minimal required permissions
• Sync data should be stored on secured network shares with appropriate ACLs
• FreeFileSync runs in silent mode without user interaction

Performance Considerations

• Sync time depends on file count, size, and network speed
• Network speed is typically the bottleneck for UNC shares
• FreeFileSync is optimized for incremental syncs
• Use filter rules to exclude temporary/unnecessary files
• Consider bandwidth throttling in FreeFileSync settings for large syncs
• Run during off-peak hours to minimize network impact

Version History

1.0.0 (2026-01-24)

• Initial production release
• Automated sync with scheduling
• FreeFileSync batch execution
• UNC share support with credential management
• Lock file and interval control
• Comprehensive error handling and logging
• Dynamic batch file path updates
• Prerequisite validation

1.0.1 (2026-01-26)

• Improve UNC path validation for network share connections
• Code formatting improvements for better readability
• Refactored parameter splatting for Invoke-ScheduledExecution

Support

For issues or questions:

1. Check the Troubleshooting section
2. Review script logs for error details
3. Verify all Requirements are met
4. Check FreeFileSync documentation at https://freefilesync.org/manual.php

License

See LICENSE in the root directory.

Related Files

• ../SchedulerTemplate.psm1 - Shared scheduling and logging module
• scriptsettings.json - Configuration file
• file-sync.bat - Batch launcher
• file-sync.ps1 - Main script
• sync.ffs_batch - FreeFileSync batch configuration

Additional Resources

• FreeFileSync Official Site: https://freefilesync.org/
• FreeFileSync Manual: https://freefilesync.org/manual.php
• FreeFileSync Forum: https://freefilesync.org/forum/