From 2fbb9de07225e927e847257de49d36008481ab80 Mon Sep 17 00:00:00 2001 From: James Ruskin Date: Fri, 14 Jun 2024 18:29:36 +0100 Subject: [PATCH] (doc) Adds Jenkins SSL Upgrade Instructions for Quickstart Guide --- .../certificate-renewal.mdx | 101 +++++++++++++++++- .../upgrade-jenkins.mdx | 9 +- 2 files changed, 107 insertions(+), 3 deletions(-) diff --git a/src/content/docs/en-us/c4b-environments/quick-start-environment/certificate-renewal.mdx b/src/content/docs/en-us/c4b-environments/quick-start-environment/certificate-renewal.mdx index e01d18ffcd4..0bf1e666395 100644 --- a/src/content/docs/en-us/c4b-environments/quick-start-environment/certificate-renewal.mdx +++ b/src/content/docs/en-us/c4b-environments/quick-start-environment/certificate-renewal.mdx @@ -8,7 +8,7 @@ import Callout from '@choco/components/Callout.astro'; import Iframe from '@choco/components/Iframe.astro'; import Xref from '@components/Xref.astro'; -This document is meant to serve as a guide for where to look when needing to renew your SSL certificate(s) for the Nexus and Chocolatey Central Management components of the quick start environment. +This document is meant to serve as a guide for where to look when needing to renew your SSL certificate(s) for the Jenkins, Nexus, and Chocolatey Central Management components of the quick start environment. ## Set-NexusCert.ps1 @@ -213,3 +213,102 @@ process { ```powershell .\Set-CCMCert.ps1 -CertificateThumbprint 'Your_Certificate_Thumbprint_Value' ``` + +## Set-JenkinsCert.ps1 + +A version of this script may already be saved on your repository server at `C:\choco-setup\scripts\Set-JenkinsCert.ps1`. + +```powershell +<# + .Synopsis + Updates a keystore and ensure Jenkins is configured to use an appropriate port and certificate for HTTPS access + + .Example + Set-JenkinsCert -Thumbprint $Thumbprint + + .Notes + Requires a Jenkins service restart after the changes have been made. +#> +[CmdletBinding()] +param( + # The thumbprint of the certificate to use + [Parameter(Mandatory)] + [String]$Thumbprint, + + # The port to have HTTPS available on + [Parameter()] + [uint16]$Port = 7443 +) + +$KeyStore = "C:\ProgramData\Jenkins\.jenkins\keystore.jks" +$KeyTool = Convert-Path "C:\Program Files\Eclipse Adoptium\jre-*.*\bin\keytool.exe" # Using Temurin*jre package keytool +$Passkey = [System.Net.NetworkCredential]::new( + "JksPassword", + "$(New-Guid)" +).Password + +if (Test-Path $KeyStore) { + Remove-Item $KeyStore -Force +} + +# Generate the Keystore file +try { + $CertificatePath = Join-Path $env:Temp "$($Thumbprint).pfx" + $CertificatePassword = [System.Net.NetworkCredential]::new( + "TemporaryCertificatePassword", + "$(New-Guid)" + ) + + # Temporarily export the certificate as a PFX + $null = Get-ChildItem Cert:\LocalMachine\TrustedPeople\ | Where-Object {$_.Thumbprint -eq $Thumbprint} | Export-PfxCertificate -FilePath $CertificatePath -Password $CertificatePassword.SecurePassword + + # Using a job to hide improper non-output streams + $Job = Start-Job { + $CurrentAlias = ($($using:CertificatePassword.Password | & $using:KeyTool -list -v -storetype PKCS12 -keystore $using:CertificatePath) -match "^Alias.*").Split(':')[1].Trim() + + $null = & $using:KeyTool -importkeystore -srckeystore $using:CertificatePath -srcstoretype PKCS12 -srcstorepass $using:CertificatePassword.Password -destkeystore $using:KeyStore -deststoretype JKS -alias $currentAlias -destalias jetty -deststorepass $using:Passkey + $null = & $using:KeyTool -keypasswd -keystore $using:KeyStore -alias jetty -storepass $using:Passkey -keypass $using:CertificatePassword.Password -new $using:Passkey + } | Wait-Job + if ($Job.State -eq 'Failed') { + $Job | Receive-Job + } else { + $Job | Remove-Job + } +} finally { + # Clean up the exported certificate + Remove-Item $CertificatePath +} + +# Update the Jenkins Configuration +$XmlPath = "C:\Program Files\Jenkins\jenkins.xml" +[xml]$Xml = Get-Content $XmlPath +@{ + httpPort = -1 + httpsPort = $Port + httpsKeyStore = $KeyStore + httpsKeyStorePassword = $Passkey +}.GetEnumerator().ForEach{ + if ($Xml.SelectSingleNode("/service/arguments")."#text" -notmatch [Regex]::Escape("--$($_.Key)=$($_.Value)")) { + $Xml.SelectSingleNode("/service/arguments")."#text" = $Xml.SelectSingleNode("/service/arguments")."#text" -replace "\s*--$($_.Key)=.+?\b", "" + $Xml.SelectSingleNode("/service/arguments")."#text" += " --$($_.Key)=$($_.Value)" + } +} +$Xml.Save($XmlPath) + +if ((Get-Service Jenkins).Status -eq 'Running') { + Restart-Service Jenkins +} +``` + +### What does this script do? + +- The script will prompt for a certificate thumbprint. Please enter the thumbprint of a certificate available in the LocalMachine\TrustedPeople store. +- Adds the certificate to the Jenkins Java Keystore. +- Modifies the `jenkins.xml` configuration file to point to the new port, keystore, and passkey. +- Restarts the Jenkins service. + +### Script Example + +```powershell +.\Set-JenkinsCert.ps1 -Thumbprint 'Your_Certificate_Thumbprint_Value' +``` \ No newline at end of file diff --git a/src/content/docs/en-us/c4b-environments/quick-start-environment/upgrade-jenkins.mdx b/src/content/docs/en-us/c4b-environments/quick-start-environment/upgrade-jenkins.mdx index b6fc8408ac8..3d658d6ac61 100644 --- a/src/content/docs/en-us/c4b-environments/quick-start-environment/upgrade-jenkins.mdx +++ b/src/content/docs/en-us/c4b-environments/quick-start-environment/upgrade-jenkins.mdx @@ -16,7 +16,7 @@ If your server is internet restricted, please internalize the needed packages on The current Jenkins package requires Java version 17 or 21 which hasn't been added as a package dependency to jenkins (due to the numerous flavours of Java out there). As part of the Quick Start Guide setup we install the temurin21jre package. However any Java version 17 or 21 package will work. - + More information is available in the [Java support policy documentation](https://www.jenkins.io/doc/book/platform-information/support-policy-java/). @@ -25,6 +25,7 @@ If your server is internet restricted, please internalize the needed packages on 1. Internalize the Jenkins package and push it to your internal repo. 2. Internalize a java package compatible with Jenkins and push it to your internal repo. We recommend the [temurin21jre package](https://community.chocolatey.org/packages/Temurin21jre). 3. Upgrade the temurin21jre and Jenkins packages (Example commands provided below). +4. Run the `Set-JenkinsCert.ps1` script to set Jenkins to run over HTTPS again. export const callout2 = { title: 'Internalizing Note', @@ -32,7 +33,7 @@ export const callout2 = { }; - You can add the temurin21jre and Jenkins packages to your Jenkins pipelines, setup by the Quick Start Guide, to help keep new versions of these packages in your internal repo. + You can add the `temurin21jre` and `jenkins` packages to your Jenkins pipelines, setup by the Quick Start Guide, to help keep new versions of these packages in your internal repo. ### Example Upgrade Commands: @@ -44,3 +45,7 @@ choco upgrade temurin21jre --package-parameters="/ADDLOCAL=FeatureJavaHome" -y - ```powershell choco upgrade jenkins -y --source="'Your Internal Repo'" ``` + +```powershell +C:\choco-setup\files\scripts\Set-JenkinsCert.ps1 -Thumbprint 'Your_Certificate_Thumbprint_Value' +```