Create a certificate and add a deployment

Create the certificate first, then add one or more deployments to it.

1. Create the certificate. Use the fully qualified domain name as the name. It becomes the subject of the issued certificate and is added to the list of domains, for example:

$cert = New-TLSPilotCertificate -Name 'web01.example.com' `
    -Domain 'web01.example.com' -Source PrivateCa

-Source accepts LetsEncrypt, ZeroSsl, Acme, WindowsEnterpriseCa and PrivateCa. Without -Source, LetsEncrypt is used. The remaining parameters depend on the source you choose: a DNS provider and a credential for a Dns01 challenge; -Http01Mode Listener (default) or WebRoot with -WebRoot for Http01; -ListenAddress (default 0.0.0.0, port 443) for TlsAlpn01; a template for the Enterprise CA; the CA id for the Private CA; and for -Source Acme the provider with -AcmeAuthorityId, the id that Get-TLSPilotAcmeProvider shows. Get-Help New-TLSPilotCertificate -Full lists all combinations.

For an ACME certificate, -Profile selects an ACME profile of the CA, for example tlsserver. Without it, TLSPilot uses CA default. -RenewOnCaEmergency sets the emergency option of the certificate to Global, On or Off. Get-TLSPilotAcmeProvider lists the configured ACME providers with their id. Global corresponds to Global setting in the dialog. -RenewalWindow (a TimeSpan, for example (New-TimeSpan -Days 20) or (New-TimeSpan -Hours 12)) sets the renewal window. Without it, TLSPilot uses the same suggestion as the dialog, from the profile or template lifetime, at most 30 days. For an Enterprise CA certificate, -RenewalWindow also switches off Follow template renewal period.

For DNS-01 Alias Mode (chapter Set up DNS-01 Alias Mode), add -DnsValidation Alias and the alias zone with -DnsAliasDomain. -DnsValidation accepts RealDomain (default) and Alias; with Alias, -DnsAliasDomain is required, otherwise the command stops with Alias domain is required for DNS-01 Alias Mode. -DnsProvider and -DnsCredentialTarget then refer to the alias zone:

$cert = New-TLSPilotCertificate -Name 'shop.example.com' `
    -Domain 'shop.example.com','www.example.org' -ChallengeType Dns01 `
    -DnsProvider cloudflare -DnsCredentialTarget 'dns/cloudflare' `
    -DnsValidation Alias -DnsAliasDomain 'servicedomain.net'

Before it saves, the command lists the required CNAME records, one line per name in the form _acme-challenge.shop.example.com → _acme-challenge.shop.example.com.servicedomain.net, followed by TLSPilot writes the TXT record in the alias zone only. See the User Manual for details. It then checks the records and reports every missing or wrong record as a warning (DNS-01 Alias Mode: …). A warning does not stop the save, but the order is refused until the records are correct. Set-TLSPilotCertificate takes the same two parameters to switch an existing certificate to Alias Mode or back, and runs the same list and check. Set-TLSPilotCertificate expects the configuration of the certificate from Get-TLSPilotConfig, not a row of Get-TLSPilotCertificate, and saves at once without -WhatIf:

$c = (Get-TLSPilotConfig).certificates | Where-Object name -eq 'shop.example.com'
Set-TLSPilotCertificate -Certificate $c -DnsValidation Alias `
    -DnsAliasDomain 'servicedomain.net'

2. Add a deployment. It tells TLSPilot where to install the certificate. Select the target with -Method, for example:

$dep = New-TLSPilotDeployment -CertificateId $cert.id `
    -Method WindowsIisBinding -Host 'web01' -SiteName 'Default Web Site'

The parameters of a target only appear once -Method is set. To see what a target needs, press Tab after the method name. The following table lists all targets and their parameters. Parameters marked with an asterisk are mandatory for the target.

Without -Host, host-based targets use localhost, the management host.

The file targets WindowsWinRmFile (File Path (WinRM)), WindowsUncShare (UNC share) and LinuxSshFile (File Path (SSH)) take five additional parameters that set the content of the files, see chapter Chain options. Other targets ignore them.

New-TLSPilotDeployment -CertificateId $cert.id -Method WindowsUncShare `
    -UncPath '\\fs01\certs' -CredentialTarget 'unc-lab' `
    -IncludeChain $true -IncludeRoot $true

Set-TLSPilotDeployment takes the same parameters and changes only those you pass. For the file targets, -FileFormat (pfx, pkcs8, pkcs1, encrypted-pem) sets the format, -KeyPassword (SecureString) the password, -PemKeyFormat (asIssued, rsa, pkcs8) the key format and -WritePasswordFile the .pwd file. -KeyPassword is required with pfx, with encrypted-pem including the key, and for LinuxSshTomcat, where it becomes the certificateKeystorePassword. Without -FileFormat, a new file target stores pkcs8; an existing format is not overwritten. -SeparateFiles defaults to $true for deployments and to $false for the export.

3. Test the target before you rely on it. Test-TLSPilotDeployment opens a real connection and authenticates, but does not install the certificate:

Test-TLSPilotDeployment -CertificateId $cert.id -DeploymentId $dep.id

You can also test a target before the deployment exists. To do so, pass -CertificateId, -Method and the parameters of the target instead of -DeploymentId. To change a deployment later or to disable it without deleting it, use Set-TLSPilotDeployment:

Set-TLSPilotDeployment -CertificateId $cert.id -Id $dep.id -Enabled $false