sf-acl-tests

Windows ACL preservation test suite for Starfish copy jobs.

Purpose

Validates that Starfish correctly:

1. Preserves ACLs when copying from source to destination
2. Detects and propagates ACL changes on subsequent copies

Prerequisites

• Windows Server 2025 (or 2019/2022)
• PowerShell 5.1+
• Administrator privileges
• Starfish agent configured

Quick Start

# Enable script execution (current session only)
Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process

# Run setup as Administrator
.\Setup-ACLTestEnvironment.ps1

Setup creates:

• Source share: \\SERVERNAME\ACLTestShare → C:\StarfishACLTest
• Destination share: \\SERVERNAME\ACLTestDest → C:\StarfishACLTest_Dest
• 6 test users, 2 groups, 1 superuser
• Directory structure with varied ACL configurations

---

Testing Workflow

Phase 1: Initial Copy Test

Tests whether Starfish preserves ACLs on initial copy.

# Step 1: Capture source ACLs (baseline)
.\Verify-Source.ps1 -Phase baseline
# Creates: source_baseline.txt

# Step 2: Configure Starfish copy job
#    Source:      \\SERVERNAME\ACLTestShare
#    Destination: \\SERVERNAME\ACLTestDest
#    Enable ACL preservation

# Step 3: Run Starfish SCAN on source

# Step 4: Run Starfish COPY job

# Step 5: Capture destination ACLs
.\Verify-Dest.ps1 -Phase after_copy
# Creates: dest_after_copy.txt

# Step 6: Compare and save results
.\Compare-ACLs.ps1 -Phase initial | Tee-Object -FilePath phase1_results.txt

Expected result: "NO DIFFERENCES - ACLs MATCH!"

---

Phase 2: Change Detection Test

Tests whether Starfish detects ACL changes and propagates them.

# Step 1: Modify source ACLs
.\Modify-ACLs.ps1
# Select scenario 1-5, or option 6 for ALL scenarios

# Step 2: Capture modified source ACLs
.\Verify-Source.ps1 -Phase modified
# Creates: source_modified.txt

# Step 3: Run Starfish RESCAN on source (same source as Phase 1)

# Step 4: Run Starfish COPY job (same destination as Phase 1)

# Step 5: Capture updated destination ACLs
.\Verify-Dest.ps1 -Phase after_update
# Creates: dest_after_update.txt

# Step 6: Compare and save results
.\Compare-ACLs.ps1 -Phase update | Tee-Object -FilePath phase2_results.txt

Expected result: "NO DIFFERENCES - ACLs MATCH!"

---

Generate Report

After completing both phases, generate a report for delivery:

.\Generate-Report.ps1
# Creates: Starfish_ACL_Test_Report.md

The report summarizes test results, includes raw output, and provides recommendations.

---

Files

File	Description
Setup-ACLTestEnvironment.ps1	Creates users, groups, directories, ACLs, shares
Verify-Source.ps1	Captures ACLs from source directory
Verify-Dest.ps1	Captures ACLs from destination directory
Compare-ACLs.ps1	Compares source vs destination reports
Modify-ACLs.ps1	Menu-driven ACL modifications for Phase 2
Generate-Report.ps1	Creates test report from results
Cleanup.ps1	Removes all test environment components
ACL-QuickReference.md	ACL/DACL/SACL/ACE concepts and PowerShell examples

---

Output Files

ACL Snapshots

File	Created By	When
source_baseline.txt	Verify-Source.ps1 -Phase baseline	Before first copy
dest_after_copy.txt	Verify-Dest.ps1 -Phase after_copy	After first copy
source_modified.txt	Verify-Source.ps1 -Phase modified	After modifying ACLs
dest_after_update.txt	Verify-Dest.ps1 -Phase after_update	After second copy

Test Results

File	Created By	Contents
phase1_results.txt	Compare-ACLs.ps1 -Phase initial	Initial copy comparison
phase2_results.txt	Compare-ACLs.ps1 -Phase update	Change detection comparison
Starfish_ACL_Test_Report.md	Generate-Report.ps1	Final report for delivery

---

Modification Scenarios

Modify-ACLs.ps1 provides these pre-built scenarios:

Option	Change	What It Tests
1	Add SF_User6 to User1_Only	Adding a new user ACE
2	Remove SF_Group2 from Complex_ACL	Removing a group ACE
3	Change SF_Group1 Modify → Read on Group1_Shared	Permission change
4	Add Deny ACE for SF_User3 on Group2_Shared	Deny ACE handling
5	Enable inheritance on No_Inheritance_Test	Inheritance change
6	Run ALL scenarios	Comprehensive test
7	RESET to original state	Re-run setup

---

Test Users

User	Group	Password
SF_User1	SF_Group1	Test@Pass123!
SF_User2	SF_Group1	Test@Pass123!
SF_User3	SF_Group2	Test@Pass123!
SF_User4	SF_Group2	Test@Pass123!
SF_User5	None	Test@Pass123!
SF_User6	None	Test@Pass123!
SF_SuperAdmin	N/A	Test@Pass123!

Note: Use SF_SuperAdmin for Starfish - has read access to all directories.

---

Directory Structure

C:\StarfishACLTest\
├── User[1-6]_Only/          # Exclusive user access (inheritance disabled)
├── Group1_Shared/           # SF_Group1 Modify access
├── Group2_Shared/           # SF_Group2 Modify access
├── Group1_ReadOnly/         # SF_Group1 Read access
├── Group2_ReadOnly/         # SF_Group2 Read access
├── Mixed_Permissions/       # Nested permission variations
│   ├── SubDir_User1/
│   ├── SubDir_Group1/
│   └── SubDir_Group2/
├── Inherited_From_Parent/   # Inheritance enabled (3 levels deep)
│   └── Level2/
│       └── Level3/
├── No_Inheritance_Test/     # Inheritance explicitly disabled
├── Deny_ACE_Test/           # Explicit Deny ACE (SF_User5 denied)
└── Complex_ACL/             # Multiple users + groups + varied permissions

---

Troubleshooting

Script won't run (execution policy)

Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process

ACLs don't match after copy

• Verify Starfish ACL preservation is enabled
• Check if destination filesystem supports ACLs (NTFS required)
• Verify Starfish service account has backup/restore privileges

Missing users/groups on destination

If copying to a different server, users and groups must exist on both machines (or use domain accounts).

---

Cleanup

Remove all test environment components when done:

# Remove everything (shares, directories, users, groups)
.\Cleanup.ps1

# Keep users/groups for future tests
.\Cleanup.ps1 -KeepUsers