What Is Posh-ACME?

Posh-ACME is a free PowerShell tool that helps you automatically get, renew, and manage SSL/TLS certificates for your websites and servers. Think of an SSL certificate as the digital ID that makes your website secure (the little padlock icon in browsers). Normally, getting and renewing these certificates is a manual, time-consuming process. Posh-ACME does it all for you automatically.

This guide will walk you through every step needed to install and set up Posh-ACME on your computer, whether you're using Windows, Linux, or macOS. No prior experience is required — just follow the steps in order.

Quick Overview

Here is a summary of what this guide covers:

Before You Begin — What You Need

Before starting the installation, make sure you have the following ready. Think of this as your checklist before cooking — gather all ingredients first!

System Requirements

• Windows users: PowerShell 5.1 or higher (already included in Windows 10 and Windows Server 2016 and later)
• Linux/macOS users: PowerShell Core 7 or higher (we'll install this if you don't have it)
• Administrator or sudo access on your computer (needed to install software)

Accounts & Credentials You'll Need

You will need to collect the following items before starting. Ask your IT admin or DNS provider if you don't have them:

• Cloudflare account with an API Token (we'll create this together in a later step)
• EAB Key ID — provided by your ACME server administrator (looks like a 40-character code)
• EAB HMAC Key — also provided by your ACME server administrator (64-character code)
• ACME Server URL — the web address of your certificate authority (e.g., https://acme.https.in/acme/directory)
• Your email address — used to register your ACME account

Part 1 — Install PowerShell (If Needed)

PowerShell is the tool that runs Posh-ACME. Windows users likely already have it. Linux and macOS users will need to install PowerShell Core 7. Follow only the section that applies to your operating system.

First: Check If PowerShell Is Already Installed

Open PowerShell (on Windows, search for 'PowerShell' in the Start menu) and type the following command, then press Enter:

$PSVersionTable.PSVersion

You should see output like this:

Major  Minor  Patch  PreReleaseLabel  BuildLabel
-----  -----  -----  ---------------  ----------
7      4      0

If the Major version number shows 7 or higher (for Linux/macOS) or 5.1 or higher (for Windows), you're good to go! Skip to Part 2. If not, follow the installation steps below for your operating system.

Installing PowerShell Core on Ubuntu or Debian Linux

Open your Linux terminal and run the following commands one by one. Copy each line exactly as shown and press Enter after each one:

sudo apt-get update

sudo apt-get install -y wget apt-transport-https software-properties-common

wget -q "https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/packages-microsoft-prod.deb"

sudo dpkg -i packages-microsoft-prod.deb

rm packages-microsoft-prod.deb

sudo apt-get update

sudo apt-get install -y powershell

pwsh

Installing PowerShell Core on CentOS or RHEL 8

Open your terminal and run these commands:

curl https://packages.microsoft.com/config/rhel/8/prod.repo | sudo tee /etc/yum.repos.d/microsoft.repo

sudo yum install -y powershell

pwsh

Installing PowerShell Core on macOS

You'll need Homebrew installed. If you don't have it, visit https://brew.sh to install it first. Then run:

brew install --cask powershell

pwsh

Verify PowerShell Is Working Correctly

After installation on any platform, confirm it's working by checking the version:

pwsh --version

Expected result:

PowerShell 7.4.0

Part 2 — Install Posh-ACME

Now that PowerShell is ready, we'll install the Posh-ACME module. A 'module' is like a plugin — it adds new features to PowerShell.

Step 1 — Install the Posh-ACME Module

There are two ways to install it. Choose the option that matches your situation:

Option A — Install just for your user account (Recommended — no admin required)

Install-Module -Name Posh-ACME -Scope CurrentUser -Force

Option B — Install for all users on this computer (requires admin/sudo)

On Windows (run PowerShell as Administrator):

Install-Module -Name Posh-ACME -Scope AllUsers -Force

On Linux or macOS (use sudo):

sudo pwsh -Command "Install-Module -Name Posh-ACME -Scope AllUsers -Force"

Step 2 — Verify the Installation

Run these commands to confirm Posh-ACME is installed correctly:

# Check that the module is listed
Get-Module -Name Posh-ACME -ListAvailable

# Load the module into this session
Import-Module Posh-ACME

# See all available commands
Get-Command -Module Posh-ACME

# Check the version number
(Get-Module Posh-ACME).Version

You should see output similar to this:

ModuleType  Version   Name       ExportedCommands
----------  -------   ----       ----------------
Script      4.23.0    Posh-ACME  {Add-DnsTxt, Complete-PAOrder, Export-PAAccountKey ...}

Step 3 — Find Where Posh-ACME Is Installed

You'll need this file path in the next step. Run this command to find it:

$modulePath = (Get-Module Posh-ACME -ListAvailable).ModuleBase
Write-Host "Posh-ACME installed at: $modulePath"

The path will look something like these depending on your operating system:

• Windows: C:\Users\YourUsername\Documents\PowerShell\Modules\Posh-ACME\4.23.0
• Linux: /home/username/.local/share/powershell/Modules/Posh-ACME/4.23.0
• macOS: /Users/username/.local/share/powershell/Modules/Posh-ACME/4.23.0

Part 3 — Increase the Timeout Limit (Very Important!)

We need to edit one file inside Posh-ACME to increase the waiting time from 2 minutes to 10 minutes. Don't worry — this is a simple text change.

Step 1 — Find the file that needs to be changed

Run this command in PowerShell. It will show you the full path to the file:

$modulePath = (Get-Module Posh-ACME -ListAvailable).ModuleBase
$finalizeScript = Join-Path $modulePath "Public\Submit-OrderFinalize.ps1"
Write-Host "Script location: $finalizeScript"

Make note of the path it shows — you'll need it in the next step.

Step 2 — Create a backup of the original file

Before changing anything, always make a backup. This command copies the file and adds '.backup' to the copy's name:

Copy-Item $finalizeScript "$finalizeScript.backup" -Force
Write-Host "Backup created!"

Step 3 — Open the file in a text editor

Choose the command that matches your operating system:

On Windows:

notepad $finalizeScript
# Or if you have VS Code installed:
code $finalizeScript

On Linux:

nano $finalizeScript
# Or:
vim $finalizeScript

On macOS:

nano $finalizeScript
# Or:
code $finalizeScript

Step 4 — Find and change the timeout values

Inside the file, scroll down to around line 200–250 and look for these two lines.

What you will see (the original/default settings):

$maxRetries = 12   # Default: 12 attempts
$retrySleep  = 10  # Default: 10 seconds between attempts

# Total timeout: 12 x 10 = 120 seconds (just 2 minutes)

Change $maxRetries from 12 to 60 so it looks like this:

$maxRetries = 60   # Changed: 60 attempts
$retrySleep  = 10  # Keep this the same: 10 seconds between attempts

# Total timeout: 60 x 10 = 600 seconds (10 minutes)

Alternative option — 15-minute timeout with more frequent checks (advanced users):

$maxRetries = 180  # 180 attempts
$retrySleep  = 5   # 5 seconds between attempts

# Total: 180 x 5 = 900 seconds (15 minutes)

Save the file and close the editor.

Step 5 — Confirm the change was saved

Run this command to double-check that your changes are in the file:

Select-String -Path $finalizeScript -Pattern "maxRetries|retrySleep" -Context 1,1

You should see:

> $maxRetries = 60
> $retrySleep  = 10

Part 4 — Set Up Your Cloudflare API Token

Posh-ACME needs permission to automatically add and remove DNS records in your Cloudflare account. It does this using an API Token — a special password that gives it exactly the permissions it needs, nothing more.

Step 1 — Log in to Cloudflare and create an API token

Follow these steps in the Cloudflare website:

1. Go to https://dash.cloudflare.com and log in to your account
2. Click on your profile icon in the top-right corner and select My Profile
3. Click on the API Tokens tab
4. Click the Create Token button
5. Click Use template next to Edit zone DNS

Now set the token permissions. Make sure these are selected:

• Zone ? DNS ? Edit
• Zone ? Zone ? Read

Under Zone Resources:

• Include ? Specific zone ? select your domain name (e.g., example.com)
• OR if you manage multiple domains: Include ? All zones

6. Click Continue to summary
7. Click Create Token
8. IMPORTANT: Copy the token immediately — Cloudflare will only show it once!

Step 2 — Test that the API token works

Let's make sure the token can actually talk to Cloudflare. Open PowerShell and run this code (replace the X's with your actual token):

# Paste your actual Cloudflare API token here
$cfToken = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

# Build the request headers
$headers = @{
    'Authorization' = "Bearer $cfToken"
    'Content-Type'  = 'application/json'
}

# Send a test request
try {
    $response = Invoke-RestMethod -Method Get `
        -Uri "https://api.cloudflare.com/client/v4/zones" `
        -Headers $headers

    if ($response.success) {
        Write-Host "Token is valid! Your accessible zones:"
        $response.result | ForEach-Object { Write-Host " - $($_.name)" }
    }
} catch {
    Write-Host "Token test failed: $($_.Exception.Message)"
}

If successful, you'll see your domain names listed. If it fails, double-check the token was copied correctly.

Part 5 — Register with the ACME Certificate Server

Now we'll connect Posh-ACME to the certificate authority (the ACME server) that will issue your SSL certificates. You'll use the EAB credentials your administrator provided.

Step 1 — Set your ACME server address

Tell Posh-ACME which certificate server to use. Replace the URL with the one your ACME admin gave you:

# Replace with your actual ACME server URL
Set-PAServer -DirectoryUrl "https://acme.https.in/acme/directory"

# Check the connection was successful
Get-PAServer | Format-List

If connected successfully, you'll see details about the server:

location   : https://acme.https.in/acme/directory
status     : Valid
nonce      : https://acme.https.in/acme/new-nonce
newAccount : https://acme.https.in/acme/new-account
newOrder   : https://acme.https.in/acme/new-order

Step 2 — Create your ACME account using EAB credentials

Now register your account. Replace all the placeholder values (the X's) with your actual EAB credentials from your administrator:

# Your EAB Key ID (40 characters) --- from your ACME admin
$eabKeyId = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

# Your HMAC Key (64 characters) --- from your ACME admin
$eabHmacKey = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

# Your email address
$email = "yourname@example.com"

# Register your account
New-PAAccount -Contact $email -ExtAcctKID $eabKeyId -ExtAcctHMACKey $eabHmacKey -AcceptTOS

# Verify account was created
Get-PAAccount | Format-List

A successful registration will show:

id      : https://acme.https.in/acme/acct/ACCOUNT_TOKEN
status  : valid
contact : {mailto:yourname@example.com}

Part 6 — Save Your Configuration

Instead of typing your credentials every time you open PowerShell, we'll create a configuration file that stores everything and loads it automatically.

Step 1 — Create the configuration file

Run this script to save all your settings to a file. Replace each placeholder value with your actual credentials:

# Where to save the configuration
$configPath = "$HOME\.poshacme-config.ps1"

# Create the file with your credentials
@"
# Posh-ACME Configuration File
`$acmeServer = "https://acme.https.in/acme/directory"
`$eabKeyId   = "YOUR_EAB_KEY_ID_HERE"
`$eabHmacKey = "YOUR_HMAC_KEY_HERE"
`$email      = "yourname@example.com"
`$cfToken    = "YOUR_CLOUDFLARE_TOKEN_HERE"

# Connect to ACME server
Set-PAServer -DirectoryUrl `$acmeServer

# Set up Cloudflare plugin credentials
`$pArgs = @{
    CFToken = (`$cfToken | ConvertTo-SecureString -AsPlainText -Force)
}

Write-Host "Configuration loaded!"
"@ | Out-File -FilePath $configPath -Encoding UTF8

Write-Host "Configuration saved to: $configPath"

Step 2 — Load the configuration

Every time you open a new PowerShell session, load your settings with this single command:

. "$HOME\.poshacme-config.ps1"

Step 3 — Optional: Auto-load configuration on every PowerShell start

If you want PowerShell to automatically load your settings every time it opens:

Step 3a: Open your PowerShell profile file

notepad $PROFILE

Step 3b: Add this line to the file

. "$HOME\.poshacme-config.ps1"

Step 3c: Save and close

Save the file and close Notepad. From now on, your Posh-ACME settings will load automatically every time you start PowerShell.

Part 7 — Using a Different DNS Provider (Optional)

This guide uses Cloudflare, but Posh-ACME supports more than 50 DNS providers. Here are the setup snippets for other popular providers. Use the one that matches your DNS host.

AWS Route 53

# First, install the AWS PowerShell module
Install-Module -Name AWS.Tools.Route53 -Scope CurrentUser -Force

# Then set up your credentials
$pArgs = @{
    R53AccessKey = "YOUR_AWS_ACCESS_KEY"
    R53SecretKey = "YOUR_AWS_SECRET_KEY" | ConvertTo-SecureString -AsPlainText -Force
}

Microsoft Azure DNS

# Install the Azure DNS module
Install-Module -Name Az.Dns -Scope CurrentUser -Force

# Log in to Azure
Connect-AzAccount

# Set up credentials
$pArgs = @{
    AZSubscriptionId = "YOUR_SUBSCRIPTION_ID"
    AZResourceGroup  = "your-resource-group-name"
}

Google Cloud DNS

# Install Google Cloud module
Install-Module -Name GoogleCloud -Scope CurrentUser -Force

$pArgs = @{
    GCloudKeyFile = "C:\path\to\your\service-account-key.json"
}

GoDaddy

$pArgs = @{
    GDKey    = "YOUR_GODADDY_API_KEY"
    GDSecret = "YOUR_GODADDY_SECRET" | ConvertTo-SecureString -AsPlainText -Force
}

DigitalOcean

$pArgs = @{
    DOToken = "YOUR_DIGITALOCEAN_TOKEN" | ConvertTo-SecureString -AsPlainText -Force
}

Part 8 — Verify Everything Is Working

Let's run a quick check to make sure all pieces are connected and working together before you start issuing certificates.

# Load your configuration
. "$HOME\.poshacme-config.ps1"

# Check ACME server connection
Get-PAServer | Select-Object location, status

# Check your ACME account
Get-PAAccount | Select-Object id, status, contact

# Test server connectivity
Test-PAServer -Verbose

Troubleshooting — Common Problems and Fixes

If something doesn't work, check the table below for your error and its solution.

Installation Checklist — Are You Done?

Use this checklist to confirm you've completed every step before moving on to issuing certificates:

What's Next?

Congratulations — you have completed the Posh-ACME installation! Your system is now fully set up to issue and renew SSL certificates automatically.

Helpful Links & Resources

• Posh-ACME Official Documentation: https://poshac.me/docs/
• GitHub Repository (report issues, view source): https://github.com/rmbolger/Posh-ACME
• Full List of Supported DNS Plugins: https://poshac.me/docs/v4/Plugins/
• Community Support & Questions: https://github.com/rmbolger/Posh-ACME/discussions
• ACME Server Support: Contact your ACME server administrator for EAB credentials and account help