Skip to content

installation.md

Latest commit

 

History

History
248 lines (172 loc) · 9.4 KB

installation.md

File metadata and controls

248 lines (172 loc) · 9.4 KB
Raw

PowerShell IT Support Toolkit — Installation Guide

1. Installation Overview

The PowerShell IT Support Toolkit is a portable, modular suite of administrative and diagnostic scripts designed for Windows environments. It provides IT Support Engineers with standardized tools for collecting system data, diagnosing network issues, inspecting logs, and performing safe system maintenance.

This guide covers how to obtain the toolkit, verify your Windows environment, configure execution policies, and validate your installation.

Basic Workflow: Prerequisites → Obtain Project → Verify Environment → Test → Run

2. System Requirements

Operating System

  • Windows 10 / Windows 11 or Windows Server 2016+.
  • The toolkit relies on core Windows features (like WMI/CIM and native networking executables) and is not compatible with Linux or macOS.

PowerShell

The toolkit is engine-agnostic and explicitly supports:

  • Windows PowerShell 5.1 (Included by default in modern Windows OS)
  • PowerShell 7+ (Core)

To verify your installed PowerShell version, run:

$PSVersionTable

Check the PSVersion and PSEdition properties. An edition of Desktop indicates Windows PowerShell 5.1, while Core indicates PowerShell 7+.

Permissions

The toolkit operates on the Principle of Least Privilege. Administrator privileges are not required to launch the toolkit or run most diagnostic scripts (e.g., checking disk space or listing user processes).

However, specific administrative operations (e.g., restarting services, reading restricted Security event logs, or creating local users) naturally require an elevated session.

3. Required PowerShell Modules and Components

The toolkit is completely self-contained and does not require any external third-party PowerShell modules to be installed from the PSGallery.

It relies exclusively on its own internal shared modules located in scripts\common\:

  • Common.psm1 — Provides shared toolkit functionality, UI formatting, and standardized output messaging (Write-Info, Write-Success, etc.).
  • Logger.psm1 — Handles centralized, safe file-based logging for toolkit operations.
  • Utilities.psm1 — Contains shared internal utility and validation functions.

These modules are automatically imported by the toolkit scripts at runtime.

4. Obtaining the Toolkit

You can obtain the toolkit by downloading a ZIP archive or cloning the repository via Git.

Using Git (Recommended for easy updates):

git clone <repository_url>
cd PowerShell-IT-Support-Toolkit

Using ZIP Download: Extract the downloaded ZIP archive to a dedicated local directory, such as C:\IT-Tools\PowerShell-IT-Support-Toolkit.

5. Project Structure

The project uses a structured, modular layout. Upon installation, ensure your directory looks similar to this:

PowerShell-IT-Support-Toolkit/
├── docs/                 (Documentation and guides)
├── scripts/
│   ├── IT-Toolkit.ps1    (Main interactive orchestrator)
│   ├── common/           (Shared internal modules)
│   ├── system/           (Diagnostic scripts: Get-Processes, Get-SystemInfo)
│   ├── services/         (Service management scripts)
│   ├── storage/          (Disk space and cleanup scripts)
│   ├── networking/       (Connectivity and DNS scripts)
│   ├── eventlogs/        (Windows Event Log extraction)
│   ├── reports/          (Comprehensive PC reporting)
│   └── automation/       (Administrative automation scripts)
├── output/               (Default directory for exported reports and logs)
└── README.md

6. Verify the Installation

After downloading the toolkit, launch PowerShell and verify the core components exist:

# Navigate to the toolkit directory
Set-Location -Path "C:\Path\To\PowerShell-IT-Support-Toolkit"

# Verify the main orchestrator script exists
Test-Path -LiteralPath ".\scripts\IT-Toolkit.ps1"

# Verify the core shared module exists
Test-Path -LiteralPath ".\scripts\common\Common.psm1"

Both commands should return True.

7. Execution Policy Considerations

Windows PowerShell restricts the execution of scripts by default to prevent accidental malicious activity.

To check your current execution policy, run:

Get-ExecutionPolicy -List

If your policy is set to Restricted, the toolkit will not run. The toolkit does not require a permanent, system-wide weakening of the execution policy (e.g., Set-ExecutionPolicy Unrestricted).

Instead, you can safely bypass the policy only for the current process:

powershell.exe -ExecutionPolicy Bypass -File ".\scripts\IT-Toolkit.ps1"

8. First Run

The primary entry point for the toolkit is the interactive menu orchestrator.

To launch it, open your PowerShell console, navigate to the project root, and execute:

.\scripts\IT-Toolkit.ps1

The orchestrator will load the required Common.psm1 module and display an interactive menu providing access to categories such as:

  1. System Information
  2. Running Processes
  3. Running Services
  4. Disk Usage
  5. Network Diagnostics
  6. Event Logs
  7. Cleanup Temp Files
  8. Generate Full PC Report
  9. Exit

9. Administrator Privileges

If you intend to perform administrative tasks, you must launch PowerShell as an Administrator before running the toolkit.

To verify if your current session is elevated, run:

$currentPrincipal = New-Object Security.Principal.WindowsPrincipal([Security.Principal.WindowsIdentity]::GetCurrent())
$currentPrincipal.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)

If it returns True, you are elevated. Use elevation only when the specific diagnostic or administrative task demands it.

10. Report Output and Export

Several toolkit scripts natively support exporting data to JSON files for offline analysis.

This is handled seamlessly via the -ExportPath parameter. When provided, the script uses the internal Export-ToolkitReport function to format and save the data.

Example of generating an offline process report:

.\scripts\system\Get-Processes.ps1 -ExportPath ".\output\Processes.json"

11. Running Individual Scripts

You are not required to use the main IT-Toolkit.ps1 menu. The toolkit's architecture ensures that every backend script is self-contained and imports its own dependencies using dynamic $PSScriptRoot paths.

This makes the toolkit highly suitable for automation. You can execute individual scripts directly:

.\scripts\system\Get-SystemInfo.ps1
.\scripts\services\Get-AllServices.ps1
.\scripts\storage\Get-DiskSpaceReport.ps1
.\scripts\networking\Invoke-NetworkDiagnostics.ps1

12. Common Installation Problems

Script Not Found

  • Symptom: "The term '.\scripts\IT-Toolkit.ps1' is not recognized..."
  • Fix: Ensure you are in the correct working directory. Check your location with Get-Location and navigate to the project root.

Module Import Problems

  • Symptom: Red error text stating Common.psm1 cannot be found.
  • Fix: Ensure the scripts\common\ directory exists and the project was extracted with its internal directory structure fully intact.

Permission Denied

  • Symptom: Access Denied errors when querying services or WMI.
  • Fix: You are attempting to run a protected command as a standard user. Restart your PowerShell console as an Administrator.

13. Updating the Toolkit

For installations managed via Git, you can safely update the toolkit by pulling the latest changes from the repository:

cd PowerShell-IT-Support-Toolkit
git status
git pull

Note: Always review local changes or exported reports in the project directory before updating to avoid overwriting your own custom configurations or data.

14. Uninstallation / Removal

The PowerShell IT Support Toolkit is entirely portable. It does not install persistent services, modify the Windows Registry, create Scheduled Tasks, or install global modules into the $env:PSModulePath.

To completely remove the toolkit from a system, simply delete the project directory:

Remove-Item -Path "C:\Path\To\PowerShell-IT-Support-Toolkit" -Recurse -Force

15. Security Considerations

  • Trusted Source: Always ensure you have obtained the toolkit from its official repository.
  • Execution Policy: Do not permanently disable script execution policies globally on your machine just to run the toolkit. Use process-level scopes (-ExecutionPolicy Bypass).
  • Review Code: Before executing any PowerShell script downloaded from the internet as an Administrator, quickly review the source code (especially administrative scripts like those in the automation/ folder).
  • Data Privacy: Toolkit reports generated via -ExportPath contain system IP addresses, usernames, and running software. Treat this exported data as sensitive.

16. Installation Verification Checklist

  • Windows OS environment verified.
  • PowerShell version checked ($PSVersionTable).
  • Project ZIP extracted or Git repository cloned.
  • scripts\IT-Toolkit.ps1 exists.
  • scripts\common\Common.psm1 exists.
  • Toolkit starts successfully without errors.
  • At least one diagnostic script (e.g., Get-Processes.ps1) executes successfully.
  • Report export functionality tested using -ExportPath.