Active Directory / Samba User Migration Scripts

Overview

This repository contains a set of two scripts designed to facilitate the migration or replication of user accounts, basic properties, group memberships, and OU structure from a source Active Directory (like Windows AD or another Samba instance) environment to a target Samba Active Directory environment.

The process involves two main steps:

1. Export: A PowerShell script (Export-ADUsersToCsv.ps1 or similar, based on powershell_export_script_commented) is run on the source environment to extract user data into a standardized CSV file.
2. Import: A Bash script (create_samba_users.sh or similar, based on samba_user_template_script) is run on the target Samba environment to read the CSV file and create/update users, OUs, and group memberships accordingly.

Use Cases:

• Migrating users from a Windows Server Active Directory domain to a Samba AD domain.
• Replicating user structures between different Samba AD domains or instances.
• Bulk creating users in a new Samba environment based on an export from another directory.

Components

1. PowerShell Export Script (powershell_export_script_commented)

   • Purpose: Connects to the source Active Directory, retrieves users from a specified OU and its sub-OUs, gathers properties (SamAccountName, GivenName, Surname, Mail, Department), resolves group memberships into names, and exports everything to a CSV file.
   • Environment: Runs on a Windows machine with PowerShell and the Active Directory module (RSAT tools) installed, typically domain-joined or with appropriate credentials.
   • Configuration: Requires setting the source $ou (Distinguished Name) to search within and the $exportPath for the output CSV file.
   • Output: A UTF8 encoded CSV file (lab_users_export.csv by default) with specific columns (see CSV Format section).

2. Bash Import Script (samba_user_template_script)

   • Purpose: Reads the standardized CSV file generated by the export script, creates specified Organizational Units (OUs) under a base OU in the target Samba AD, creates/replaces user accounts with specified properties and passwords, sets password expiry, and adds users to specified groups.
   • Environment: Runs on a Linux machine that is part of the target Samba AD domain (or can connect via samba-tool) with Bash and samba-tool installed.
   • Configuration: Requires setting the CSV_FILE path, target BASE_OU, target DOMAIN_DN, default/admin passwords, home directory template, and user deletion behavior.
   • Input: Expects a CSV file matching the format generated by the export script.

Migration Workflow

1. Prepare Source Environment:
   • Ensure the Active Directory PowerShell module is installed on the machine where you'll run the export script.
   • Identify the Distinguished Name (DN) of the top-level OU containing the users you want to export.
2. Configure & Run Export Script:
   • Edit the PowerShell export script (powershell_export_script_commented) and set the correct $ou and $exportPath variables.
   • Run the PowerShell script with sufficient permissions to read AD user data.
   • Verify the CSV file (lab_users_export.csv or your configured name) is created successfully.
3. Transfer CSV:
   • Securely transfer the generated CSV file from the source environment to the Linux machine where you will run the import script.
4. Prepare Target Environment:
   • Ensure the Linux machine has samba-tool installed and configured to interact with the target Samba AD domain.
   • Verify the target base OU structure (e.g., OU=LABOR if your BASE_OU is OU=LAB USERS,OU=LABOR) exists or that the script runner has permission to create it.
5. Configure & Run Import Script:
   • Edit the Bash import script (samba_user_template_script) and set all configuration variables correctly: CSV_FILE (path to the transferred CSV), BASE_OU, DOMAIN_DN, passwords, HOME_DIRECTORY_TEMPLATE, ENABLE_USER_DELETION.
   • Make the script executable (chmod +x create_samba_users.sh).
   • BACKUP YOUR TARGET SAMBA AD DATA.
   • TEST with a small subset of users first by creating a smaller test CSV.
   • Run the Bash script (likely requiring sudo) with sufficient permissions to create OUs, create/delete users, and manage group memberships in the target Samba AD.
6. Verify Results:
   • Review the output of the import script for any errors or warnings.
   • Use tools like samba-tool, Active Directory Users and Computers (if applicable), or other LDAP browsers to verify that users, OUs, and group memberships were created correctly in the target Samba AD environment.
   • Test user logins.

CSV File Format (Crucial Bridge)

The consistency of the CSV file format between the export and import scripts is critical. The expected format is:

• Encoding: UTF8
• Delimiter: Comma (,)
• Header Row: Expected by the import script (which skips it). The export script generates it.
• Columns (Order Matters):
  1. SamAccountName (Username)
  2. GivenName (First Name)
  3. Surname (Last Name)
  4. Mail (Email Address)
  5. Department (Department Name)
  6. Folder (Name of the specific OU under the target BASE_OU)
  7. MemberOf (List of group names, semicolon-separated e.g., Group1; Group2; Group3)

Note: The PowerShell export script is specifically designed to produce the semicolon-separated MemberOf format required by the Bash import script.

Important Considerations & Warnings

• BACKUP: Always back up both your source AD (before export, just in case) and especially your target Samba AD (before import) environments.
• TESTING: Never run the import script directly on a production environment without extensive testing using a small, representative sample of users in a test environment or OU.
• PERMISSIONS: Ensure the accounts running the export and import scripts have the necessary read (source) and write/create/delete (target) permissions in their respective Active Directory environments. Running the import script often requires root or equivalent privileges on the Linux machine.
• PASSWORDS: The import script sets initial passwords. These must meet the target domain's password policy. Users will likely need to change these passwords upon first login. This process does not migrate existing passwords.
• DATA CLEANUP: Review the exported CSV file before importing. You may need to manually clean up or adjust data (e.g., fix names, map old group names to new ones if necessary, correct OU folder names).
• OU STRUCTURE: The import script creates OUs based on the Folder column directly under the configured BASE_OU. Ensure this target structure is desired. The scripts provided do not handle deeply nested or complex OU migrations automatically.
• HOME DIRECTORIES: The import script sets the home directory attribute in Samba AD. It does not create the actual directory on the file system or set file/share permissions. This requires separate provisioning steps.
• CONFLICTING OBJECTS: The import script includes an option (ENABLE_USER_DELETION) to delete existing users before creation. Use this with extreme caution. If disabled, the script will error if a user already exists. Decide on the desired behavior for existing accounts.
• GROUP EXISTENCE: The import script attempts to add users to the groups listed in the CSV. It assumes these groups already exist in the target Samba AD. You may need a separate process to create groups first if they don't exist.

Troubleshooting

• Carefully read the output of both scripts for specific error messages.
• Verify all configured paths (OU DNs, file paths) are correct in both scripts.
• Double-check permissions for the users running the scripts.
• Ensure the CSV file is correctly formatted and transferred without corruption.
• Check Samba logs (/var/log/samba/ or similar) on the target server for more detailed error information.

---

[Creative Commons Zero v1.0 Universal]