diff --git a/docs/pingcastle/4.0/enterpriseinstall.md b/docs/pingcastle/4.0/enterpriseinstall.md index 89adda72f3..923b724cf5 100644 --- a/docs/pingcastle/4.0/enterpriseinstall.md +++ b/docs/pingcastle/4.0/enterpriseinstall.md @@ -34,6 +34,10 @@ For SQL Express, visit [SQL Server Express Downloads](https://learn.microsoft.co #### Step 2 - Run PingCastleEnterpriseInstaller.exe (production) +:::note +Having trouble installing? See [Collecting Installer Logs](/docs/pingcastle/4.0/enterprisetroubleshooting#collecting-installer-logs) in the Troubleshooting guide. +::: + The installer wizard walks you through prerequisite checks, licensing, and configuration screens in the following order. 1. **Prerequisite check**: the installer checks the server for IIS and the ASP.NET 10.0 Hosting Bundle. If either is missing, it offers to install them for you. @@ -65,7 +69,7 @@ The installer wizard walks you through prerequisite checks, licensing, and confi ::: :::tip Remote SQL Server Setup - If you're configuring a remote SQL Server (not on the local machine), see the [Remote Database Configuration](#remote-database-configuration) section for detailed setup instructions including SQL Authentication and Windows Authentication options. + If you're configuring a remote SQL Server (not on the local machine), see the [Remote Database Configuration](#remote-database-configuration) section for setup instructions covering SQL Authentication and Windows Authentication. ::: 7. **Authentication method**: enable **Windows Authentication**, **OpenID Connect**, **SAML2**, or a combination, and optionally disable local password login. See [Authentication](enterpriseauthsetup.md#authentication) for full configuration details for each method. @@ -125,10 +129,14 @@ choco install sql-server-express #### Step 2 - Run PingCastleEnterpriseInstaller.exe (test/POC) +:::note +Having trouble installing? See [Collecting Installer Logs](/docs/pingcastle/4.0/enterprisetroubleshooting#collecting-installer-logs) in the Troubleshooting guide. +::: + 1. Run PingCastleEnterpriseInstaller.exe. The installer checks for IIS and the ASP.NET 10.0 Hosting Bundle and offers to install them if they're missing. :::warning - Installing missing prerequisites can require a server restart. If prompted, restart the server and run the installer again to continue. + Installing missing prerequisites can require a server restart. If the installer prompts you to restart, restart the server and run the installer again to continue. ::: 2. Accept the license agreement and enter your license key. @@ -144,7 +152,7 @@ For a detailed description of each wizard screen, see the Production Installatio ::: :::tip Remote SQL Server Setup -If you're configuring a remote SQL Server instead of using the local instance, see the [Remote Database Configuration](#remote-database-configuration) section for detailed setup instructions including SQL Authentication and Windows Authentication options. +If you're configuring a remote SQL Server instead of using the local instance, see the [Remote Database Configuration](#remote-database-configuration) section for setup instructions covering SQL Authentication and Windows Authentication. ::: @@ -162,7 +170,7 @@ PingCastle Enterprise requires a database user account with database owner permi ### SQL Server Permissions -When connecting to an existing database, the account PingCastle Enterprise uses requires database owner permissions. If PingCastle Enterprise runs under the IIS application pool's Windows account, grant permissions with the following SQL: +When you connect to an existing database, the account PingCastle Enterprise uses requires database owner permissions. If PingCastle Enterprise runs under the IIS application pool's Windows account, grant permissions with the following SQL: ```sql IF NOT EXISTS (SELECT loginname FROM master.dbo.syslogins diff --git a/docs/pingcastle/4.0/enterprisetroubleshooting.md b/docs/pingcastle/4.0/enterprisetroubleshooting.md index 76e6c65f14..8806e5ff71 100644 --- a/docs/pingcastle/4.0/enterprisetroubleshooting.md +++ b/docs/pingcastle/4.0/enterprisetroubleshooting.md @@ -7,7 +7,7 @@ sidebar_label: Troubleshooting ### Viewing Application Logs and Errors -When troubleshooting issues with PingCastle Enterprise, you need to view error messages and logs to diagnose problems. +To diagnose problems with PingCastle Enterprise, view its error messages and logs. Configure logging from the web portal at **Configuration** > **Settings** > **Logging**: @@ -54,6 +54,18 @@ Before pasting file contents into any online JSON validator, redact passwords, c Only restart the PingCastle Enterprise application pool or service after the file passes validation. +### Collecting Installer Logs + +If the installer fails or exits unexpectedly, generate a verbose installer log to diagnose the issue or attach to a support case. + +Run the installer with the `/l*v` flag and a log file path: + +``` +pingcastle-enterprise-installer.exe /l*v C:\path\to\install.log +``` + +Include this log file when opening a support case for installation issues. + ### Common Errors and Solutions Here are common errors, their causes, and how to fix them. @@ -121,7 +133,7 @@ You can find more detailed error messages in the event log or by running the app - Invalid license key - Missing or misconfigured application settings -- Runtime dependencies not installed +- Missing runtime dependencies **Solution:** diff --git a/docs/pingcastle/4.0/enterpriseupgrade.md b/docs/pingcastle/4.0/enterpriseupgrade.md index fa2e31ed92..4d4a8297eb 100644 --- a/docs/pingcastle/4.0/enterpriseupgrade.md +++ b/docs/pingcastle/4.0/enterpriseupgrade.md @@ -26,6 +26,16 @@ Test the upgrade in a non-production environment first if one is available. This PingCastle Enterprise 4.0 replaces the MSI-based installer with a single installer executable, `PingCastleEnterpriseInstaller.exe`. Upgrading from 3.5.1 to 4.0 is an in-place upgrade: you run the new installer on top of your existing 3.5.1 installation, and it detects and upgrades that installation automatically. The installer also detects and applies any prerequisite changes 4.0 requires, such as the correct ASP.NET Hosting Bundle version, so you don't need to update prerequisites manually. +:::warning Known Issue +In this release, the installer sometimes fails to detect the existing installation directory during an upgrade. If this happens, run the installer from the command line and specify the installation directory with the `INSTALLFOLDER` parameter: + +``` +pingcastle-enterprise-installer.exe INSTALLFOLDER="D:\PingCastleEnterprise\" /l*v upgrade.log +``` + +Replace `D:\PingCastleEnterprise\` with your actual installation directory. +::: + To upgrade PingCastle Enterprise from 3.5.1 to 4.0: 1. Download `PingCastleEnterpriseInstaller.exe` for version 4.0. @@ -34,7 +44,7 @@ To upgrade PingCastle Enterprise from 3.5.1 to 4.0: ![A screenshot of the installer installing the required ASP.NET Hosting Bundle version as part of the upgrade.](/images/pingcastle/enterpriseupgrade/prereq-install.webp) - The installer bundles the required prerequisites, including the ASP.NET Hosting Bundle, directly. The upgrade doesn't need web access to download them. + The installer bundles the required prerequisites directly, including the ASP.NET Hosting Bundle. The upgrade doesn't need web access to download them. ## Configuration migration