diff --git a/docs/accessanalyzer/26.1/install/installer-reference.md b/docs/accessanalyzer/26.1/install/installer-reference.md index 41b8a9e710..38437cecd8 100644 --- a/docs/accessanalyzer/26.1/install/installer-reference.md +++ b/docs/accessanalyzer/26.1/install/installer-reference.md @@ -21,27 +21,53 @@ Two environment variable names need care: `--hostname` reads `DSPM_HOSTNAME`, no | Flag | Environment variable | Default | Description | |---|---|---|---| -| `--license-key` | `LICENSE_KEY` | none | Netwrix license key. Required. Validated online before the install starts. | -| `--hostname` | `DSPM_HOSTNAME` | none | Fully qualified domain name users open in their browsers. Lowercased before use. | +| `--license-key` | `LICENSE_KEY` | none | Netwrix license key. Required. The installer validates it online before the install starts. | +| `--hostname` | `DSPM_HOSTNAME` | none | Fully qualified domain name users open in their browsers. The installer lowercases it before use. | | `--first-admin-email` | `FIRST_ADMIN_EMAIL` | none | Email address of the first administrator. Required. Becomes that person's username. | | `--first-admin-name` | `FIRST_ADMIN_NAME` | none | Full name of the first administrator. | | `--tls-cert` | `TLS_CERT_FILE` | `/etc/dspm/tls.crt` | PEM TLS certificate file, full chain with the leaf certificate first. Requires `--tls-key`. | | `--tls-key` | `TLS_KEY_FILE` | `/etc/dspm/tls.key` | PEM TLS private key file. Requires `--tls-cert`. | | `--ca-bundle` | `TLS_CA_BUNDLE_FILE` | none | PEM certificate authority (CA) bundle. Needed when a private CA issued the certificate. | -| `--size` | `SIZE` | `medium` | Deployment size: `small`, `medium`, `large`, or `enterprise`. Case-insensitive. | +| `--size` | `SIZE` | `medium` | Deployment size: `small`, `medium`, `large`, or `enterprise`. Case-insensitive. See [Size](requirements.md#size) for the CPU, RAM, and disk each size requires. | | `--target-revision` | `TARGET_REVISION` | `1.*` | Release version to install, such as `1.5.0`. The default installs the latest 1.x release. Also appears as **Target Revision** under **Show advanced settings?**. | | `--accept-warnings` | `ACCEPT_WARNINGS` | `false` | Continue past preflight warnings without asking. | -| `--assume-yes` | `DSPM_ASSUME_YES` | `false` | Skip the review screen shown when the configuration file already supplies every required value. | +| `--assume-yes` | `DSPM_ASSUME_YES` | `false` | Skip the review screen that appears when the configuration file already supplies every required value. | | `--dry-run` | `DRY_RUN` | `false` | Print the planned actions and exit without installing. Needs no TLS files and writes no configuration file. | | `--log-level` | `LOG_LEVEL` | `info` | Detail written to the log file: `debug`, `info`, `warn`, or `error`. | | `--postgres-data-dir` | `POSTGRES_DATA_DIR` | none | Custom directory for the application database's data. | | `--clickhouse-data-dir` | `CLICKHOUSE_DATA_DIR` | none | Custom directory for the analytics store's data. | +| `--log-exports-storage` | `LOG_EXPORTS_STORAGE` | none | Persistent volume claim (PVC) size for log exports, such as `10Gi`. | | `--skip-preflight` | `SKIP_PREFLIGHT` | `false` | Skip the preflight checks. Intended for testing only. | | `--version` | — | — | Print the installer version and exit. | | `--help` | — | — | Print flag help and exit. | The defaults for `--tls-cert` and `--tls-key` apply only when you omit both flags. Supplying one without the other is an error: `--tls-cert and --tls-key must both be provided together`. +### Advanced Flags + +These flags control the underlying Kubernetes platform, ArgoCD, and Helm chart the installer manages. Most installs never need them — they exist for troubleshooting, custom environments, and uninstalling. + +| Flag | Environment variable | Default | Description | +|---|---|---|---| +| `--k3s-version` | none | `v1.33.4+k3s1` | K3s version to install. | +| `--k3s-name` | none | `dspm` | K3s service and instance name. | +| `--kubeconfig` | `KUBECONFIG` | `/etc/rancher/k3s/k3s.yaml` | Path to the kubeconfig file. | +| `--argocd-version` | none | `3.2.0` | ArgoCD image tag. | +| `--argocd-namespace` | none | `argocd` | Kubernetes namespace for ArgoCD. | +| `--argocd-reconciliation-timeout` | none | `1h` | How often ArgoCD self-heals configuration drift. The version-poller CronJob detects new releases separately. | +| `--disable-dex` | none | `true` | Disable the Dex identity provider. | +| `--disable-notifications` | none | `true` | Disable the ArgoCD notifications controller. | +| `--helm-namespace` | none | `default` | Kubernetes namespace for the Helm chart. | +| `--helm-values` | none | none | Path to a Helm values YAML file. | +| `--chart` | none | none | Chart name, for custom chart sources. | +| `--repo` | none | none | Helm repository URL, for custom chart sources. | +| `--release` | none | none | Helm release name, for custom chart sources. | +| `--local-charts-dir` | `LOCAL_CHARTS_DIR` | none | Mount a local Helm chart directory into `argocd-repo-server` and install from it with a `file://` source, instead of a remote repository. | +| `--use-mirrored-images` | none | `true` | Pull container images from the Netwrix mirror registry. | +| `--set` | none | none | Inline Helm value override in `key=value` form. Repeatable. | +| `--uninstall` | `DSPM_UNINSTALL` | `false` | Uninstall k3s and permanently delete all Access Analyzer data. Prompts for confirmation unless you pass `--force`. | +| `--force` | `DSPM_FORCE` | `false` | Skip the confirmation prompt for `--uninstall`. | + A custom data directory must be an absolute path to an existing, writable directory. It can't be `/`, can't sit under `/bin`, `/sbin`, `/boot`, `/dev`, `/etc`, `/lib`, `/lib64`, `/proc`, `/root`, `/run`, `/sys`, `/usr`, or `/var/log`, and can't contain quotes, backslashes, dollar signs, or backticks. ### Value Checks @@ -50,9 +76,9 @@ The installer rejects bad values before it changes anything on the server. | Value | Rules | |---|---| -| License key | Letters, digits, hyphens, and underscores only. Checked online; an expired, suspended, unknown, or invalid key stops the install with exit code 10. If the installer can't reach the licensing service, it warns and continues. | +| License key | Letters, digits, hyphens, and underscores only. The installer checks it online; an expired, suspended, unknown, or invalid key stops the install with exit code 10. If the installer can't reach the licensing service, it warns and continues. | | Hostname | Must contain a dot, must not be an IP address, must not end in `.localhost`, and must not exceed 253 characters. Each dot-separated part is 1 to 63 letters, digits, or hyphens and can't start or end with a hyphen. | -| First administrator email | A plain address such as `admin@corp.example.com`, with a dotted domain and without a display name, quotes, backslashes, or spaces. Lowercased before use. | +| First administrator email | A plain address such as `admin@corp.example.com`, with a dotted domain and without a display name, quotes, backslashes, or spaces. The installer lowercases it before use. | | TLS certificate and key | PEM. The pair must match, the certificate must not be expired, and its Subject Alternative Names must include the hostname. A certificate that expires within 30 days produces a warning in the log. | | CA bundle | PEM with at least one certificate. The TLS certificate must chain to it. If the TLS certificate is self-signed and you give no bundle, the installer uses the certificate as its own bundle. | @@ -83,7 +109,7 @@ When the file supplies every required value and the installer runs in a terminal | 0 | Success. | | 1 | General failure: an invalid flag value, a hostname or TLS validation error, a required value missing in a non-interactive run, or prompts canceled with Esc or Ctrl-C (`installation cancelled`). | | 10 | License key error. The key is expired, suspended, not found, or invalid. | -| 20 | The release version requested with `--target-revision` isn't available for this license key. | +| 20 | The release version you requested with `--target-revision` isn't available for this license key. | | 50 | The installer couldn't install the platform, or the platform didn't become ready within 5 minutes. | | 60 | The installer couldn't install a platform component. | | 70 | The Access Analyzer services didn't all become healthy within 30 minutes, or you pressed Ctrl-C while waiting for them. | @@ -103,11 +129,11 @@ The installer compares RAM and disk against their thresholds with a 5% tolerance | `disk` | Free space on `/var/lib` against the 40 GB floor. | FAIL | ` GB free on /var/lib; at least 40 GB is needed to install` | | `disk` | Free space on `/var/lib` against the size's recommended disk. | WARN | ` GB free on /var/lib; the size is designed to hold GB, so it will run out as data accumulates` | | `cgroups` | The kernel exposes cgroups at `/sys/fs/cgroup`. | FAIL | `cgroups not available at /sys/fs/cgroup` | -| `kernel-modules` | The `br_netfilter` and `overlay` modules are loaded or built in. The install loads missing modules itself, so this check warns only when it can't inspect a module, or during a dry run when a module isn't loaded. | WARN | `kernel module issues: : could not check module: ` or `kernel module issues: : not loaded (dry run; will not be modprobed)` | +| `kernel-modules` | The kernel has the `br_netfilter` and `overlay` modules loaded or built in. The install loads missing modules itself, so this check warns only when it can't inspect a module, or during a dry run when a module isn't loaded. | WARN | `kernel module issues: : could not check module: ` or `kernel module issues: : not loaded (dry run; will not be modprobed)` | | `os` | The Linux distribution belongs to a recognized family. | WARN | `unrecognised Linux distribution; installation may not be supported` | | `selinux` | SELinux isn't in enforcing mode. | WARN | The message says SELinux is enforcing and asks you to allow the platform's container policy or set SELinux to permissive. | | `antivirus` | No known antivirus product is installed or running: `mdatp`, CrowdStrike, ClamAV, Sophos, Carbon Black, or Trend Micro. | WARN | `antivirus software detected: (exclusion hint: )` | -| `network` | Each of the 18 required hosts resolves in DNS and accepts a connection on port 443 within 5 seconds. | FAIL when a name doesn't resolve; WARN when a connection times out or is refused | `DNS resolution failed for: ` or `connection failed (timeout/refused) for: ` | +| `network` | Each of the 18 required hosts resolves in DNS and accepts a connection on port 443 within 5 seconds. | FAIL when a name doesn't resolve; WARN when a connection times out or the host refuses it | `DNS resolution failed for: ` or `connection failed (timeout/refused) for: ` | | `domain-join` | Whether the server belongs to an Active Directory domain. Informational only. | — | `no AD domain detected`, or a message naming the detected domain | | `clock-sync` | A time-sync service (`chronyd`, `ntpd`, or `systemd-timesyncd`) is running. | WARN | `no clock sync daemon detected; Kerberos authentication requires clocks within 5 minutes of the AD domain controller — install chronyd, ntpd, or systemd-timesyncd to eliminate clock-skew risk` | @@ -135,5 +161,5 @@ Exit codes: 0 when everything is healthy, 70 when the timeout passes, 71 when a | File | Contents | |---|---| -| `/var/log/dspm-installer.log` | Everything the installer does, as one JavaScript Object Notation (JSON) object per line, at the detail set by `--log-level`. The installer appends to the file on every run, with mode `0640`. If the installer can't write the file, it sends the same output to the terminal's standard error as text. | +| `/var/log/dspm-installer.log` | Everything the installer does, as one JavaScript Object Notation (JSON) object per line, at the detail `--log-level` sets. The installer appends to the file on every run, with mode `0640`. If the installer can't write the file, it sends the same output to the terminal's standard error as text. | | `/var/log/dspm-preflight.json` | The full result of the most recent preflight run: `timestamp`, `overallStatus`, and a `checks` list with `name`, `status`, and `message` for every check, including the ones that passed. `--dry-run` doesn't write it. | diff --git a/docs/accessanalyzer/26.1/install/run-the-installer.md b/docs/accessanalyzer/26.1/install/run-the-installer.md index 192dbc62c2..5c9b9bcccf 100644 --- a/docs/accessanalyzer/26.1/install/run-the-installer.md +++ b/docs/accessanalyzer/26.1/install/run-the-installer.md @@ -69,6 +69,16 @@ The installer expects the certificate at `/etc/dspm/tls.crt` and the private key If a private certificate authority (CA) issued the certificate, copy its CA bundle too. `/etc/dspm/ca-bundle.pem` is a convenient place; the installer asks for the path. +:::note +The installer rejects the certificate if it doesn't cover the hostname you enter at the **Hostname** prompt. Confirm the certificate's subject before you run the installer: + +```bash +openssl x509 -in /etc/dspm/tls.crt -noout -subject -nameopt multiline +``` + +Enter the exact hostname that appears in the output, for example `commonName=dspm.corp.example.com`. +::: + ## Run the Installer Run the installer with `sudo`. The `-E` flag carries your environment through to root, so the installer reads the `LICENSE_KEY` you exported for the download instead of prompting for it. @@ -79,7 +89,7 @@ sudo -E dspm-installer If your `sudo` policy doesn't allow `-E`, pass the variable inline instead: `sudo LICENSE_KEY="$LICENSE_KEY" dspm-installer`. -The installer runs its preflight checks first, then collects any value it doesn't have yet. You can let it ask, or supply everything up front. +The installer runs its preflight checks first, then collects any value it doesn't have yet. You can let it ask, or supply everything in advance. @@ -121,6 +131,23 @@ If `/etc/dspm/installer.yaml` exists from an earlier run and you're in a termina Every flag also has an environment variable, listed in the [Installer reference](installer-reference.md). + + + +Whether you answer prompts or pass flags, the installer saves the following values to `/etc/dspm/installer.yaml`. A later run reads this file first and only asks for (or requires) values that are still missing. + +```yaml +first-admin-email: admin@example.com +first-admin-name: Jane Doe +hostname: dspm.example.com +license-key: XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXX9 +tls-cert: /etc/dspm/tls.crt +tls-key: /etc/dspm/tls.key +ca-bundle: /etc/dspm/ca-bundle.pem +``` + +`ca-bundle` only appears if you gave a CA bundle path. The installer stores the license key in plain text in this file, so restrict access to it the same way you restrict `/etc/dspm/tls.key`. + @@ -135,7 +162,7 @@ The installer checks the server first, under the heading `Running preflight chec A `[FAIL]` stops the install. There's no way to override it: fix the server or choose a smaller size, then run the installer again. Failures cover CPU cores, RAM, the 40 GB disk floor, DNS resolution of the hosts the installer downloads from, and the availability of cgroups, a kernel feature the platform depends on. -A `[WARN]` is a condition the install can continue past, such as less disk than the size recommends, no time-sync service, or antivirus software that may need exclusions. In a terminal the installer asks **Continue despite these warnings?**; answer **Yes** to go on. Without a terminal, warnings stop the install unless you pass `--accept-warnings`. +A `[WARN]` is a condition the install can continue past, such as less disk than the size recommends, no time-sync service, or antivirus software that may need exclusions. In a terminal the installer asks **Continue despite these warnings?**; answer **Yes** to continue. Without a terminal, warnings stop the install unless you pass `--accept-warnings`. The full list of checks, thresholds, and messages is in the [Installer reference](installer-reference.md#preflight-checks). The installer also writes the complete result of each run to `/var/log/dspm-preflight.json` (a `--dry-run` doesn't write it). @@ -149,6 +176,27 @@ After the checks and prompts, the installer validates the certificate and hostna If the platform or the services don't become ready inside those limits, the installer stops with a non-zero exit code; the [Installer reference](installer-reference.md#exit-codes) lists the codes. If creating the first administrator fails, the installer prints a warning and still finishes. The installer logs everything it does to `/var/log/dspm-installer.log`. +
+Troubleshooting: check per-service status in ArgoCD + +The installer's progress line only reports how many services are running, not which ones are degraded. If phase 2 is taking longer than expected and you need a visual, service-by-service view, open the ArgoCD UI. + +Retrieve the initial admin password: + +```bash +sudo kubectl get secret -n argocd argocd-initial-admin-secret -o jsonpath='{.data.password}' | base64 -d && echo +``` + +Forward the ArgoCD server so you can reach it in a browser: + +```bash +sudo kubectl port-forward -n argocd svc/argocd-server 8080:80 --address 0.0.0.0 +``` + +Open `http://:8080`, sign in as `admin` with the password you retrieved, and check each application's health and sync status. + +
+ ## Install Summary The installer prints a summary. It contains: