> This is part 1 of 7 of the full documentation (pages 1–100 of 640). > The content is paginated: fetch every part to see all of it. > Next part: https://wiki.datadike.com/llms-full.txt/1 > Page index: https://wiki.datadike.com/llms.txt # Welcome Guides to deploy, administer, and audit DataDike products. | Product | What it covers | | ------------------------ | ----------------------------------------------------------------------------------------------- | | [DataDike PAM](/pam) | Privileged access management: assets, credentials, access control, and recorded sessions. | | [DataDike SONAR](/sonar) | Unified endpoint management: inventory, remote access, automation, patching, and user activity. | {% hint style="info" %} Documentation for DataDike CVESafe is published in the [knowledge base](https://wiki.datadike.com/). {% endhint %} # DataDike PAM documentation Everything needed to deploy, administer, and audit DataDike PAM. | Where to start | What it covers | | ---------------------- | --------------------------------------------------------- | | **Get started** | Concepts, architecture, and your first steps | | **Administration** | Day-to-day administration | | **Deploy and operate** | Install, cluster, upgrade, back up, and monitor | | **Reference** | API, configuration fields, ports, and supported platforms | | **Release notes** | What changed in each release | # Get started | Page | What it covers | | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [What is DataDike PAM](/pam/get-started/what-is-datadike-pam) | What DataDike PAM does and the problem it solves: it holds the credentials of privileged accounts, hands them out without showing them, brokers the sessions that use them, and records each one. | | [Architecture and components](/pam/get-started/architecture) | The components a running instance is made of, what each one does, how a session travels between them, and how the network path from the solution to an asset is formed. | | [Core concepts](/pam/get-started/core-concepts) | The vocabulary DataDike PAM uses, and how the objects relate to each other. | | [A tour of the console](/pam/get-started/console-tour) | How the console is divided into areas, how to switch between them and between organizations, and which screen holds each kind of object. | | [Onboard your first managed asset](/pam/get-started/first-managed-asset) | The end-to-end path from an empty instance to a recorded session: register an asset, choose its platform, register the account, write the authorization, connect, and find the recording in the audit trail. | # What is DataDike PAM What DataDike PAM does and the problem it solves: it holds the credentials of privileged accounts, hands them out without showing them, brokers the sessions that use them, and records each one. DataDike PAM is a privileged access management solution. It holds the credentials of the privileged accounts on your infrastructure, gives authorized people the use of those credentials without showing them, brokers the sessions they open, and keeps a record of what happened in each one. The model is one mediated point. The user authenticates to the solution as themselves; the solution authenticates to the target with the stored credential; the traffic passes through the solution, so it can be restricted while it runs and replayed afterwards. The user needs no route to the target and never learns its password. If the vocabulary is new — asset, account, platform, authorization — read [Core concepts](/pam/get-started/core-concepts) first. That page describes the objects; this one describes the product. ## The problem it solves Privileged credentials spread. The `root` password is shared between administrators, a service account password is pasted into a script, a database password sits in a configuration file, and operators reach targets directly from their workstations. That pattern has four costs: * **No attribution.** Several people know the same password, so an action on the target cannot be tied to a person. * **No evidence.** Nothing records what was typed or seen, so an incident cannot be reconstructed. * **No revocation.** Withdrawing one person's access means changing a password on every target that person knew. * **Exposure.** The target must be reachable from the operator's workstation, which means the network has to permit it. DataDike PAM removes the shared secret from circulation. The credential stays in the vault, the person authenticates as themselves, and every access travels through a route that is authorized, filtered, and recorded. ## How an access happens 1. **The user authenticates to the solution**, with multi-factor authentication when the [login policy](/pam/administration/access/login-policies) requires it. Login can also be restricted by source IP and by time of day. 2. **Authorizations decide what they see.** A user with no [authorization](/pam/administration/access/authorizations) sees no assets, whatever else they may hold. Access can be standing, or requested on demand as [just-in-time access](/pam/administration/access/just-in-time). 3. **Approval, when the rule requires it.** A request waits for the approvers named on the rule; two or more approvers gives dual custody. 4. **The credential is retrieved from the vault** and injected into the target's login by the solution. The password is not shown to the person asking for the access, and where policy does allow it to be revealed, the user must re-authenticate first. 5. **The session is opened through the solution** — directly, through a jump host, or over a reverse path from a network that accepts no inbound connections. 6. **The session is watched while it runs.** Commands are captured and classified, [command filters](/pam/administration/access/command-filtering) alert on or block what they match, an auditor can watch and terminate a live session, and behaviour analytics scores the access for anomalies. 7. **When the session ends**, temporary grants are revoked automatically, and revoking a grant terminates the sessions running under it. 8. **The record remains.** The session entry, its replay, the commands typed, and the files transferred stay in the [audit trail](/pam/administration/audit/audit-trail) for the configured retention period. ## What it manages | Category | What it covers | | ---------------------- | ------------------------------------------------------------------------------------------------- | | Servers | Windows Server (2003 to 2025) and Windows desktops, Linux distributions, Unix and AIX (5L to 7.3) | | Databases | Oracle, SQL Server, MySQL, MariaDB, PostgreSQL, MongoDB, Redis, ClickHouse, DB2, Dameng | | Network devices | Switches, routers, firewalls and out-of-band consoles, over SSH and Telnet | | Container platforms | Kubernetes clusters | | Web and cloud | Web applications, and the consoles of Azure, AWS and GCP | | Published applications | RemoteApp on Windows and virtual applications on Linux, without publishing a whole desktop | Sessions run either in the browser — web terminal, remote desktop, database client, file explorer — or through the user's own client, such as PuTTY, `mstsc.exe`, or DBeaver. The solution is the proxy in both cases, and both are recorded. See [Connection methods](/pam/administration/sessions/connection-methods). ## How credentials are handled The vault is the centre of the product. Secrets are stored in the solution's own encrypted vault, or the storage is delegated to a corporate vault you already run — HashiCorp Vault, Azure Key Vault, or AWS Secrets Manager. See [The credential vault](/pam/administration/accounts/vault). Around it: * **Discovery** finds assets on the network and in cloud accounts, and collects the accounts that already exist on them, so that an account nobody registered stops being invisible. * **Rotation** changes passwords on a schedule, after use, or on expiry, across servers, databases, web applications, network devices and mainframe, over SSH, WinRM, RPC or REST. See [Rotate credentials](/pam/administration/accounts/rotation). * **Reconciliation** detects that the solution has lost control of a password and changes it using another credential to take control back. * **Application-to-application access** serves secrets to scripts, scanners and pipelines through an API, so credentials stop being embedded in source code and configuration files. {% hint style="info" %} **Key custody.** The vault's encryption key stays under the customer's exclusive control. When an external HSM or KMS is used over PKCS#11, the master key never leaves the customer's cryptographic device. Neither DataDike nor the partner performing the deployment has access to the vault key, and the product carries no backdoor for it. {% endhint %} {% hint style="warning" %} Recovery of the backup encryption key can be split across several administrators, so that a predefined number of them must be present to reassemble it. This is deliberate: the point is that the vault key is never in one person's possession. {% endhint %} ## Agentless, with two exceptions Nothing has to be installed on a managed target. Account collection, password changes and session brokering all run over protocols the target already exposes — SSH, WinRM, RDP, the database protocols — so onboarding a device does not mean a software rollout. Two optional agents exist, and knowing why keeps the claim honest: | Agent | Why it exists | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Windows endpoint agent | Collects asset information, runs local tasks, and integrates with Windows account management on servers where that is wanted | | Connector | Installed on an isolated machine that has no jump host in front of it, so the machine can publish itself over a reverse path. See [Broker](/pam/administration/connectivity/broker) | Neither is required to manage an asset. ## Where it runs * As an appliance in your own data centre, or as a service hosted by DataDike. * On a single node, or as a high-availability cluster of several nodes behind one virtual address, with the database, cache and shared storage replicated between them. * The access components are independent per protocol, so they can be scaled and upgraded one at a time without stopping the product. * The console is reached over HTTPS from Firefox, Chrome, Edge, Opera or Safari. The interface is available in Portuguese, English, Spanish and French. See [Architecture and components](/pam/get-started/architecture) for what those pieces are and how a session travels between them. ## Related pages * [Core concepts](/pam/get-started/core-concepts) — the objects and the vocabulary * [Architecture and components](/pam/get-started/architecture) — the software that runs the product * [A tour of the console](/pam/get-started/console-tour) — where everything lives * [Onboard your first managed asset](/pam/get-started/first-managed-asset) — the whole model in one exercise # Architecture and components The components a running instance is made of, what each one does, how a session travels between them, and how the network path from the solution to an asset is formed. An instance is not a single program. It is a **core** that owns the database, the vault and every access decision, surrounded by **independent components** — one per protocol family, plus the services that store recordings, run scheduled work, and send notifications. They register themselves with the core and are listed, monitored and scaled individually. Knowing which component does what is what turns "the PAM is down" into "RDP is down and SSH is fine". {% hint style="info" %} This page is about the software that runs the product. The objects you administer — assets, accounts, authorizations — are in [Core concepts](/pam/get-started/core-concepts). Installing and sizing the components belongs to Deploy and operate. {% endhint %} ## The path of a session 1. **The user authenticates against the core.** The core is the REST API behind the console and behind every integration. It resolves the authorization, the account, the platform, and the network path to use. 2. **The core hands the session to the component that speaks the protocol** — the terminal connector for SSH, Telnet and SFTP, the graphical connector for RDP and VNC, the database connector for database protocols, the virtual application connector for published applications. 3. **That component connects to the asset** — directly, through a jump host, or over the reverse path — retrieving the credential from the core and injecting it into the target's login. The credential is never handed to the user's browser or client. 4. **While traffic flows, the component captures it**: commands typed, terminal output, screen frames, files transferred. It also enforces the command filters as it goes, which is why filtering works the same way for a web session and for a native client. 5. **When the session ends**, the component hands the replay file to the recording service, which writes it to the configured object storage. Graphical recordings pass through the video processing service first, to be transcoded into a replayable form. 6. **The task service** runs everything scheduled around all of this — credential rotation, account collection, connectivity checks, log cleanup — and the notification service delivers what the subscriptions ask for. {% hint style="warning" %} Two consequences of that shape, both worth remembering before you diagnose anything. **The core is a single point of decision**: while it is offline the console and the API are unreachable and no new session can start. **The protocol components fail independently**: with the graphical connector down, RDP and VNC sessions stop while SSH sessions keep working normally. {% endhint %} ## The components | Component | What it does | What is lost while it is offline | | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | | **Core (API)** | The REST API. Serves the console and integrations, owns the database and the vault, and makes every access decision | Everything. The console is inaccessible and no session can start | | **Task service** | Asynchronous and scheduled work: rotation, account collection, connectivity checks, cleanup | All automation. Sessions still work, but nothing scheduled runs | | **Terminal connector** | Proxy for SSH, Telnet and SFTP. Records commands, terminal output and the replay file. Serves both the web terminal and native clients | Terminal sessions, in the browser and by client | | **Graphical connector** | Proxy for RDP and VNC. Records the desktop session as video | Graphical sessions | | **Database connector** | Proxy for database sessions, so external database clients reach the asset through the solution with the queries audited | Database sessions with a native client | | **Virtual application connector** | Publishes individual applications from a remote server — RemoteApp and virtual apps — mediated and recorded, without a full desktop | Published-application sessions | | **Recording service** | Receives replay files from the protocol components and stores them in the object storage backend | New recordings. Sessions still run | | **Video processing service** | Transcodes graphical recordings into the replay format used by the audit screens | Replay of new graphical sessions | | **Notification service** | Sends email, SMS and the other configured channels | Alerts and approval notifications | | **Facial recognition service** | Identity verification by facial biometrics at login or during a session, when enabled | That verification method | | **Windows endpoint agent** | Optional agent on a Windows server: asset information, local tasks, and Windows account management | The features that depend on it, on that host only | In the console, a component is named `[Type]-ServerName` — `[Terminal]-DATADIKE-T`, `[Database]-DATADIKE`. Clicking the name opens its details. ## How components join the instance Components register themselves with the core. **System Settings › Components › Basic** holds the switch: | Setting | What it controls | | --------------------- | ------------------------------------------------------------------------------------------------------------------------- | | **Registration** | Enabled by default. Allows any component that knows the server address to register itself after being installed | | **Client connection** | Whether users may launch a native SSH client. Disabled, every terminal access is forced through the recorded web terminal | | **Database proxy** | Enables the database connector platform-wide. Disabled, native database client sessions disappear from the whole product | {% hint style="warning" %} **Turn Registration off once the components are in place.** While it is on, anything that can reach the server address can register itself as a component. Re-enable it only for as long as it takes to add a new one. {% endhint %} ## Watching component health **System Settings › Components › Components** lists every registered component in real time. It is the first screen to open when access misbehaves for one protocol and not another. | Column | What it tells you | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | **Name** | `[Type]-ServerName` | | **Online sessions** | Sessions this component is handling right now. Zero means idle; a persistently high number means it is time to add another instance of that type | | **Stat** | CPU and memory use of the component process. Close to 100% is saturation | | **Load status** | `Normal`, `Offline` — not responding, check the service on its host — or `High load` | | **ID** | The component's unique identifier, as used in logs and diagnostics | | **Type** | Which of the components above it is | | **Remote address** | Address and port of the host it runs on | {% hint style="info" %} Do not rely on someone opening this screen. An `Offline` core or connector is an availability incident, so subscribe an external monitor — Zabbix, Prometheus, Datadog — to the health endpoint and alert from there. Checking the list is a routine, not a detection mechanism. {% endhint %} ## The network path to an asset When the solution cannot open a connection to the asset itself, one of four objects supplies the route. Two of them are halves of the same mechanism, which is the most common source of confusion here. | Object | Direction | What it is | | -------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [**Proxy**](/pam/administration/connectivity/proxy) | Solution → network | The **zone**: the record that groups the jump machines of one network, and that assets are attached to. A data centre, a cloud, a VPC | | [**Gateway**](/pam/administration/connectivity/gateways) | Solution → network | The **jump machine itself**, registered inside a proxy. The solution opens a session on it, with an account registered on it, and forwards traffic to the asset from inside | | [**Broker**](/pam/administration/connectivity/broker) | Network → solution | A meeting point on a zero-trust overlay, reachable by both sides. Remote gateways dial *out* to it, the solution connects to it too, and they meet there. For networks that can accept no inbound connection | | **Connector** | Network → solution | An agent on the target machine itself, which enrols that one host with the broker and publishes only itself. For the isolated machine with no gateway in its network | {% hint style="warning" %} **Proxy and gateway are not two mechanisms.** The proxy is the zone you attach assets to; the gateways are the machines registered inside it. There is no separate proxy engine configured elsewhere. An asset uses **a proxy or a broker gateway, never both** — its registration makes you choose. {% endhint %} The component that talks to the broker from the solution's side is redundant by design: there is one instance per cluster node, each with its own identity, automatic enrolment, and self-recovery. Losing a node does not interrupt reverse access, and neither does losing a broker node. ## Reaching the console from outside Users connect to the console over **HTTPS on 443** and, from there, open RDP, SSH, Telnet, VNC and database sessions. No direct connectivity between the user and the protected devices is required — which is the point, and what makes third-party access workable without a VPN. {% hint style="danger" %} Do not publish the console straight to the internet without a firewall and a WAF in front of it. If that protection is not in place, restrict access to a controlled VPN instead. {% endhint %} For the ports the solution uses to reach *assets*, see [Ports and protocols](/pam/reference/ports). ## Single node and cluster The same components run in both shapes. What a cluster adds: | Property | In a cluster | | -------------------------- | ----------------------------------------------------------------------------------------------------------- | | Database | Replicated between nodes, with automatic election of the primary | | Cache and queue | Replicated, with failover | | Recordings and attachments | On storage shared between the nodes | | Address | One virtual address in front of the nodes, so the URL does not change when a node fails | | Sessions | Active-active: the session load is distributed across nodes, and redistributed when one becomes unavailable | | Upgrades | Components are updated individually, without stopping the product | The design targets for the active-active arrangement are **RTO of one hour or less** and **RPO of fifteen minutes or less**. ## Common errors | Symptom | Cause | Fix | | ------------------------------------------------------------ | --------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | The console is unreachable and no session starts | The core is offline | Recover the core first; nothing else can be diagnosed until it answers | | RDP fails, SSH works | The graphical connector is offline or saturated | Check **Load status** and **Stat** for that component | | Sessions run but no replay appears in the audit trail | The recording service, the video processing service, or the storage backend | Check those components, then the storage configuration | | Nothing scheduled runs, but sessions are fine | The task service is offline | Rotation, collection and cleanup all depend on it | | A newly installed component does not appear in the list | **Registration** is disabled | Enable it, register the component, then disable it again | | Component shows `Normal` but sessions are slow | High resource use rather than a fault | Read **Stat**; near 100% means add another instance of that type | | The option to launch a database client is missing everywhere | **Database proxy** is disabled in **System Settings › Components › Basic** | Enable it | ## Related pages * [Core concepts](/pam/get-started/core-concepts) — the objects the components act on * [Proxy](/pam/administration/connectivity/proxy) — the zone assets attach to * [Gateways](/pam/administration/connectivity/gateways) — the jump machines inside it * [Broker](/pam/administration/connectivity/broker) — the reverse path * [Ports and protocols](/pam/reference/ports) — the ports used to reach assets # Core concepts The vocabulary DataDike PAM uses, and how the objects relate to each other. Read this before the administration guides. DataDike PAM has a small vocabulary, and almost every screen in the console is one of the objects below. Learning the six that matter first makes the rest of this documentation read quickly. ## The chain, in one sentence A **user** is granted an **authorization** that lets them open a **session** to an **account** on an **asset**, over a protocol allowed by that asset's **platform**, through a network path provided by a **gateway** — and the whole session is recorded. Everything else is a refinement of that sentence. ## The objects ### Asset Anything the solution brokers access to: a Linux or Windows server, a network device, a database, a web application, a cloud host. An asset is not a credential — it is the destination. Assets live under **Environment › Assets** and are organized in a folder tree. ### Platform The *kind* of asset, and what can be done with it: which protocols it accepts, which port each one uses, and which automations it supports — collecting accounts, changing a password, pushing a new account. A platform is why the solution knows that an asset can be reached over SSH on port 22 but not over RDP. Assets inherit their capabilities from the platform assigned to them. Platforms live under **Environment › Platforms**. ### Account A credential on an asset — `root` on a Linux server, `Administrator` on a Windows host, a database login. The account is what the solution stores, rotates, and hands out. Users normally never see its secret. Accounts live under **Accounts › Accounts**, and always belong to exactly one asset. ### Template A reusable account definition, so that the same account can exist on many assets without being described one by one. Change the template and the change can be propagated to every asset it covers. Templates live under **Accounts › Templates**. ### Authorization The rule that connects the three sides: **who** (users or groups), **what** (assets and accounts), and **how** (which protocols, during which hours, with which command restrictions). No access exists without one. Authorizations live under **Policies › Authorization**. ### Session A connection opened through the solution. While it runs it can be watched and terminated; after it ends the recording stays in the audit trail. A session is the unit that auditing is built on. Sessions live under the **Audit** profile. ## The network path Four objects describe how the solution reaches an asset, and they are easy to confuse. | Object | What it is | | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | **Proxy** | A zone — the record that groups the jump machines of one network, and that assets are attached to. A data centre, a cloud, a VPC | | **Gateway** | The jump machine itself, registered inside a proxy. The solution opens a session on it and forwards traffic to the asset through it | | **Broker** | A reverse path, where the target dials out to the solution instead of the solution dialing in — for networks that cannot accept inbound connections | | **Connector** | The agent installed on a machine that has no gateway in front of it, so that the machine hosts its own path | ## Identity | Object | What it is | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | **User** | Someone who logs in to the console or opens sessions | | **Group** | A set of users, used as the subject of authorizations | | **Profile** | What a user may do *in the console* — administer, audit, or only consume access. Distinct from an authorization, which governs access to assets | Users can be local to the solution or synchronized from a directory. See [LDAP and Active Directory](/pam/administration/identities/ldap-and-ad). ## Two distinctions worth getting right **Authorization is not profile.** A profile decides which console screens a person sees. An authorization decides which assets and accounts they may reach. An auditor may hold a powerful profile and no authorization at all. **Account is not user.** An account is a credential *on a target*. A user is a person *of the solution*. The point of a privileged access solution is that the two are never the same thing: the person authenticates as themselves, and the solution supplies the target credential. ## Related pages * [Architecture and components](/pam/get-started/architecture) — the pieces that run the solution * [A tour of the console](/pam/get-started/console-tour) — where each object lives * [Onboard your first managed asset](/pam/get-started/first-managed-asset) — the vocabulary in practice * [Authorizations](/pam/administration/access/authorizations) # A tour of the console How the console is divided into areas, how to switch between them and between organizations, and which screen holds each kind of object. The console is one web application divided into **areas**, selected from the bar at the top. Each area serves a different job — consuming access, administering the environment, auditing it — and which areas you see depends on your role, not on a preference. Almost every screen is a list of one of the objects described in [Core concepts](/pam/get-started/core-concepts). Once you know which area an object lives in, the interface stops needing a tour. ## The areas | Area | Who works here | What it holds | | --------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | **Cockpit** | Everyone who consumes access | The assets you are authorized to reach, the sessions you open, your requests, your files, your own vault | | **Sysadmin** | Administrators | Assets, platforms, accounts, authorizations, users, connectivity — everything that defines the environment | | **Audit** | Auditors and administrators | Sessions and their recordings, commands, logins, password changes, operations, reports | | **System settings** | Administrators | Instance-wide configuration: authentication providers, security, notifications, storage, retention, components, licensing | | **Personal settings** | Everyone | Your own profile, password, MFA, SSH key, API access key, connection tokens, and web-terminal preferences | The three built-in organization roles line up with the first three areas: an *Org User* works in Cockpit, an *Org Admin* in Sysadmin, an *Org Auditor* in Audit. Custom roles mix them per module — see [Roles and permissions](/pam/administration/identities/roles). {% hint style="info" %} An area you cannot see is a role question, not a bug. If a menu entry is missing, check the permissions on your role before looking anywhere else. {% endhint %} ## Switching organization The same top bar carries the **organization selector**. Each organization is an isolated tenant: its own users, assets, accounts, authorizations, tags and audit records, with nothing shared between them. This matters more than it looks. An asset you created is only visible in the organization you were in when you created it, and an auditor sees only their own organization's sessions. When something you registered "has disappeared", check the selector first. ## Sysadmin, group by group | Group | Screens | What you do there | | --------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | — | **Dashboard** | Sessions today, sessions online, user and device counts, trend charts, device distribution by type, and rankings of most active users and devices over today, 7 days or 30 days | | **Environment** | **Discover**, **Assets**, **Platforms** | Register the devices to protect, scan networks and clouds for new ones, and manage the platform each asset belongs to | | **Gateway** | **Proxy**, **Brokers**, **Connectors** | The network paths: zones and their jump machines, the reverse-access broker, and the agents on machines that publish themselves | | **Accounts** | **Accounts**, **Templates**, **Automations** | The credentials the solution manages, the reusable definitions behind them, and the scheduled work — rotation, collection, provisioning, vault backup | | **Policies** | **Authorization**, **Just in time**, **User login**, **Command inspection**, **Asset login**, **Connect method**, **UEBA** | Who may reach what, how, when, with which commands allowed, and what happens when behaviour looks anomalous | | **Users** | **Users**, **Groups**, **Profiles** | The people who log in, the groups authorizations are written against, and the roles that decide what they may do in the console | | **Others** | **Tags** | Labels used to filter asset lists and scope reports | {% hint style="warning" %} **Nothing under Environment grants access.** Registering an asset and its account makes them manageable, not reachable. Access exists only where an [authorization](/pam/administration/access/authorizations) says so. {% endhint %} ## Audit, group by group | Group | Screens | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | — | **Dashboard**, and **UEBA** for the behaviour baseline, risk scores and anomalies | | **Sessions** | **Online** for live monitoring and termination, **Recordings**, **Keylogger** for the commands typed, **Transfers** for files moved, **Requests** for access requests | | **Console** | **Login log**, **Session records**, **Online users**, **Password changes** | | **Log audit** | **Action log** — creation, modification and deletion of objects | | **Operation audit** | **Job list** and **Executions** — the automations and each of their runs | | **Reports** | **Builder** and **Scheduled** | **Session records** is the screen most investigations start from: every session that has been opened, with its user, asset, account, protocol, start and end times, duration, and the button that plays the recording back. See [Audit trail](/pam/administration/audit/audit-trail) for what each record answers. ## Cockpit, group by group | Group | Screens | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | — | **Dashboard**, **Access** — the assets you may reach — and **Vault**, your own credentials for external sites and applications | | **JIT** | **My requests** and **To approve** | | **Files** | **File transfer** and **File explorer**, for moving and browsing files on remote devices | | **Automations** | **Commands** for ad-hoc execution across several assets, **Job list** for scheduled work replacing cron and Windows Scheduler, **Templates**, **Executions**, and **Tools** for quick ping, telnet, tcpdump and traceroute checks | **Access** is the screen a regular user lives in. Each entry shows the device name, its address, the platform, the connectivity status, and the account to use; the tree on the right filters by folder and by **Favorites**. Opening a session from here offers the methods your policies allow: | Method | What it is | Protocols | | ----------------- | ----------------------------- | --------------------------------------------------------- | | **Web CLI** | Terminal in the browser | SSH, Telnet | | **Web GUI** | Remote desktop in the browser | RDP, VNC | | **Native client** | Your own local client | SSH, RDP | | **DB client** | Database access | MySQL, PostgreSQL, Oracle and the other supported engines | See [Connection methods](/pam/administration/sessions/connection-methods) for how the available methods are restricted. ## Where each object lives | Object | Where | | ------------------------------------------------ | ----------------------------------------------------------- | | Asset | **Environment › Assets** | | Platform | **Environment › Platforms** | | Network and cloud scan | **Environment › Discover** | | Account | **Accounts › Accounts** | | Account template | **Accounts › Templates** | | Rotation, collection, provisioning, vault backup | **Accounts › Automations** | | Authorization | **Policies › Authorization** | | Command filter | **Policies › Command inspection** | | Login restriction | **Policies › User login** | | Proxy zone and its gateways | **Gateway › Proxy** | | Broker and its remote gateways | **Gateway › Brokers** | | User, group, role | **Users › Users**, **Users › Groups**, **Users › Profiles** | | Tag | **Others › Tags** | | Live session | **Audit › Sessions › Online** | | Finished session and its recording | **Audit › Console › Session records** | | Commands typed in a session | **Audit › Sessions › Keylogger** | | Report | **Audit › Reports** | | Retention windows | **System settings › Retention** | | Authentication providers | **System settings › Authentication** | | Component health | **System settings › Components** | ## Common errors | Symptom | Cause | Fix | | --------------------------------------------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------- | | An area or menu entry is missing | Your role does not grant that module | Check the role's permissions — see [Roles](/pam/administration/identities/roles) | | An asset you registered is not in the list | You are in a different organization now | Switch back with the organization selector in the top bar | | An auditor sees no sessions | Sessions belong to another organization | Audit visibility is scoped per organization | | The user has assets in Cockpit but no connection method appears | A connect method rule denies every method for them | Review **Policies › Connect method** | | A session has a record but no replay | Recording was disabled, or retention has passed | See [Session recordings](/pam/administration/audit/recordings) | ## Related pages * [Core concepts](/pam/get-started/core-concepts) — what each object in these lists is * [Roles and permissions](/pam/administration/identities/roles) — what decides which areas you see * [Onboard your first managed asset](/pam/get-started/first-managed-asset) — these screens used in order * [Audit trail](/pam/administration/audit/audit-trail) — the Audit area in detail # Onboard your first managed asset The end-to-end path from an empty instance to a recorded session: register an asset, choose its platform, register the account, write the authorization, connect, and find the recording in the audit tr This is the whole product in one exercise. By the end you will have an asset the solution manages, a credential it holds and never shows, a rule that grants one person the use of it, and a session in the audit trail that can be replayed. Each step below links to the page that covers it properly. Read this page for the **order and the decisions**; read the linked pages for the fields. {% hint style="info" %} Choose the simplest possible first asset: a Linux host the solution can already reach over SSH, with a local account whose password you know. Prove the chain on that, then repeat it on the awkward cases. Onboarding a segmented Windows host behind a broker as your first exercise means debugging four things at once. {% endhint %} If the words *asset*, *platform*, *account* and *authorization* are not yet distinct in your mind, read [Core concepts](/pam/get-started/core-concepts) first — this page uses all four. ## Before you start * A role that gives you the **Sysadmin** area. See [Roles and permissions](/pam/administration/identities/roles). * A **second user** with no privileges beyond Cockpit, to receive the authorization. Granting it to yourself works, but testing with someone who starts with nothing is what actually proves the rule is doing the granting. * The target's **address** and a **credential** on it — username and password, or an SSH key. * Network reachability from the solution to the asset, on the protocol's port. If there is none, step 1 is where you deal with it. {% hint style="warning" %} **Import the licence first.** Until the licence is imported, functions are disabled, and the symptom is features that appear to exist and do nothing. Licensing lives in **System settings**. {% endhint %} {% hint style="warning" %} **Check the server's clock and time zone before anything else.** One-time passwords are second-precision, so a drifted clock produces `OTP code invalid, or server time error` at login and blocks you out of the console for reasons that look nothing like a clock problem. {% endhint %} ## Steps ### 1. Decide the network path Do this first, because the asset's registration makes you commit to it. | Situation | What you configure | | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | The solution has a route to the asset itself | Nothing. This is the case to choose for your first asset | | Only one machine of the target network is reachable | A [Proxy](/pam/administration/connectivity/proxy) — the zone — with the jump machine registered inside it as a [Gateway](/pam/administration/connectivity/gateways) | | No route at all, or no inbound connection is permitted | A [Broker](/pam/administration/connectivity/broker), which the remote side dials out to | {% hint style="warning" %} An asset uses **a proxy or a broker gateway, never both**. Proxy and gateway are two halves of one mechanism — the zone and the machine inside it — not two alternatives. {% endhint %} ### 2. Choose the platform The platform is what tells the solution which protocols the asset accepts and on which ports, so it has to be right before the asset is registered. Open **Environment › Platforms** and find the built-in one that matches the technology — *Linux*, with SSH on 22, for a Linux host. Built-in platforms cannot be edited, only **duplicated**. If you need a variant, duplicate it and change the copy. See [Platforms](/pam/administration/assets/platforms). {% hint style="info" %} The port on a platform is the **default inherited** by assets registered against it afterwards. Changing it later does not move assets already registered — that needs **Sync protocols to assets**. {% endhint %} ### 3. Register the asset In **Environment › Assets**, create the asset with its name, its address, and the platform from the previous step. File it in a folder while you are there — reorganizing later is much more work than filing now. Then run **Test Connection** on the card. Registering an asset and being able to reach it are different things, and the card looks identical either way. See [Asset inventory](/pam/administration/assets/inventory). For a network segment with many hosts, register the first one by hand and then use [Discover](/pam/administration/assets/discovery) for the rest. ### 4. Register the account In **Accounts › Accounts**, create the account against the asset you just registered: the username, the secret, and two decisions that are easy to skip and awkward to fix later — * mark it **Privileged** if it holds administrative rights on the target; * set **su/sudo** if the account must elevate after logging in. Save, then use **Test selected** to confirm the credential actually authenticates. See [Managed accounts](/pam/administration/accounts/managed-accounts). {% hint style="info" %} If the same credential exists on many assets, do not register it repeatedly — use an [account template](/pam/administration/accounts/account-templates). And if the accounts already exist on the target and you do not know all of them, collect them from the asset instead of typing them in. {% endhint %} ### 5. Write the authorization This is the step that grants access. Everything before it only made the asset manageable. In **Policies › Authorization**, create a rule that joins the three sides: * **Who** — the test user, or better, a group they belong to. * **What** — the asset (or the folder it sits in) and the account you registered. * **How** — the protocol, at minimum the **Connect** action, and a validity period. Name the rule so that it says who gets what: the name is the first thing an auditor reads. See [Authorizations](/pam/administration/access/authorizations). {% hint style="warning" %} A rule can save cleanly and still grant nothing, because it is inactive or outside its validity window. Check the **Valid** column, not the fact that the rule exists. {% endhint %} ### 6. Open the session Sign in as the granted user and open **Access** in the **Cockpit** area. The asset must be listed there; if it is not, the rule is not reaching that user and there is no point connecting. Connect with **Web CLI** for SSH. You will not be asked for the target's password — the solution injects it. Run two or three harmless commands (`hostname`, `id`, `uptime`) so the recording has something in it. Other methods — the browser desktop, a native client, a database client — are covered in [Connection methods](/pam/administration/sessions/connection-methods). ### 7. Find it in the audit trail Back in an administrator or auditor session, open **Audit › Console › Session records**. The session you just ran is there, with its user, asset, account, protocol, start and end times and duration, and a button that replays it. See [Audit trail](/pam/administration/audit/audit-trail). ## What you should see * The asset as a card under the folder you filed it in, badged `ACTIVE`, with the effective protocols and ports of its platform. * The account listed against that asset, with the date of its last update. * The authorization in the rule list with **Valid** showing that it is in force. * The asset present in the granted user's **Access** list, and absent from the list of a user with no rule. * One entry in **Audit › Console › Session records** for the session you opened. ## How to verify it worked **The recorded session in the audit trail is the verification.** Nothing before step 7 proves the chain — an asset can be registered and unreachable, an account can be stored and wrong, a rule can exist and grant nothing. 1. Open **Audit › Console › Session records** and find the session by user and time. 2. Check the three columns that matter: the **user** is the person who connected, not a shared identity; the **asset** is yours; the **account** is the one you registered. Together they are the proof that attribution and credential injection both worked. 3. Play the **recording**. The commands you ran must be visible in it. See [Session recordings](/pam/administration/audit/recordings). 4. For SSH or Telnet, open **Audit › Sessions › Keylogger** and confirm those same commands are listed individually, with timestamps. 5. As a negative check, set the authorization **Active** off and reload the granted user's **Access** list. The asset must disappear. That is what confirms the authorization is granting the access, and not something else you configured along the way. If the session record is there but the replay is not, the chain worked and the problem is recording or storage, not access. ## Common errors | Symptom | Cause | Fix | | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- | | Screens are present but features do nothing | The licence has not been imported | Import it under **System settings** | | `OTP code invalid, or server time error` at login | The server clock has drifted; OTP is second-precision | Correct the time and time zone on the node, and keep it synchronized | | The asset saves but **Test Connection** fails, though the host answers ping | Wrong effective port, or no account yet to test with | Compare **Protocols** under the asset's **Basic** tab against the host | | The session is refused over a protocol you expected | The platform does not offer it | The platform is wrong, not the asset. Check **Environment › Platforms** | | The account saves but authentication fails on the target | The stored secret does not match the target | Nothing in the registration reveals this. Only **Test selected** or a real session does | | The granted user sees no assets at all | The rule reaches neither the user nor a group they belong to, or it is inactive or expired | Check the rule's subject, then its **Valid** column | | The asset appears but the session is refused | The protocol is not in the rule's protocol list, or the account selection excludes it | Fix the rule, not the asset | | The asset appears but no connection method is offered | A connect method rule denies every method for that user | Review **Policies › Connect method** | | The session record exists with no replay | Recording was off for that asset, or retention has passed | Check the recording configuration and **System settings › Retention** | ## Where to go next Once one asset works end to end, the rest of the environment is repetition plus policy: * Register the remaining assets in bulk with [Discover](/pam/administration/assets/discovery), and file them with [folders and tags](/pam/administration/assets/folders-and-tags). * Stop typing credentials one by one with [account templates](/pam/administration/accounts/account-templates), and put them on a schedule with [rotation](/pam/administration/accounts/rotation). * Restrict what may be run inside a granted session with [command inspection](/pam/administration/access/command-filtering). * Replace standing grants with [just-in-time access](/pam/administration/access/just-in-time) where the access is occasional. * Bring the people in from your directory with [LDAP and Active Directory](/pam/administration/identities/ldap-and-ad) and require [MFA](/pam/administration/identities/mfa). ## Related pages * [Core concepts](/pam/get-started/core-concepts) — the four objects this page chains together * [Asset inventory](/pam/administration/assets/inventory) and [Platforms](/pam/administration/assets/platforms) * [Managed accounts](/pam/administration/accounts/managed-accounts) * [Authorizations](/pam/administration/access/authorizations) * [Audit trail](/pam/administration/audit/audit-trail) # Administration | Page | What it covers | | ------------------------------------------------------ | -------------- | | [Assets](/pam/administration/assets) | | | [Accounts](/pam/administration/accounts) | | | [Access control](/pam/administration/access) | | | [Sessions](/pam/administration/sessions) | | | [Users and identities](/pam/administration/identities) | | | [Connectivity](/pam/administration/connectivity) | | | [Behavior analytics](/pam/administration/ueba) | | | [Audit](/pam/administration/audit) | | | [Integrations](/pam/administration/integrations) | | # Assets | Page | What it covers | | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Asset inventory](/pam/administration/assets/inventory) | Register, organize, test, and remove the devices the solution protects, and read what its details panel tells you. | | [Discover assets on the network](/pam/administration/assets/discovery) | Find assets automatically — from a cloud provider account or by scanning an IP range — and let sync policies file them into the inventory. | | [Platforms](/pam/administration/assets/platforms) | What a platform defines, how the list is organized, and a description of every built-in platform for hosts, databases, network devices, cloud, and web. | | [Folders and tags](/pam/administration/assets/folders-and-tags) | Build the asset folder tree, file assets into it, and use folders as the target of rules — plus what tags do that folders do not. | # Asset inventory Register, organize, test, and remove the devices the solution protects, and read what its details panel tells you. ## What this is and when to use it The inventory holds every device the solution protects: servers, network equipment, databases, web applications, and cloud resources. It is where an asset is registered, filed, tested, and removed. {% hint style="info" %} The menu calls it **Assets**; the screen's own title is **Devices**. They are the same thing. {% endhint %} ## Before you start * The platform the asset belongs to. The platform decides which protocols and ports are available — see [Platforms](/pam/administration/assets/platforms). * The folder structure you want, at least in outline. Filing assets as you create them is far cheaper than reorganizing later. ## Steps 1. Open **Environment › Assets**. 2. Click **Create**. 3. Fill the **name** and the **address** — IP or hostname. 4. Choose the **platform**. The protocols and ports come from it. 5. Save. 6. Select the asset and run **Test Connection**. 7. Under the details panel, use **Node** to file it in a folder and **Tags** to label it. ## What you should see ![The Devices screen, with assets grouped by category and the folder panel](https://1085357737-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7xzJyi9JVzRwnV6JzUho%2Fuploads%2Fgit-blob-50ffc238b22c4f2949f1cd44628f0347d2a512a5%2Fasset-inventory.png?alt=media) **1** How many assets the current filter returns. **2** One asset card: platform type, name, address, and state. **3** The folder panel, with Asset Folders and Type Folders as two views of the same inventory. Assets appear as **cards grouped by category** — **HOST**, **DATABASE**, **WEB**, and **CLOUD**, the same categories as platforms. A group appears only when at least one asset belongs to it, and each group header carries its own **Upload** button for importing assets of that category from a file. Each card shows the platform type, the name, the address, and badges for the platform and the state — `ACTIVE` when the asset is enabled. ## How to verify it worked 1. Run **Test Connection** from the card. Registration and reachability are different things, and the card looks identical either way. 2. Open the asset's details and check the **Protocols** line under **Basic**. The effective ports must be the ones you expect — `rdp:3389`, `winrm:5985`. If they are wrong, the platform is wrong, not the asset. 3. Confirm the asset appears under the folder you filed it in. ## Actions on a card | Action | What it does | | --------------- | ------------------------------------------------------------------------------ | | Asset details | Opens the details panel | | Test Connection | Tests connectivity with the device | | Edit | Opens the edit form | | Duplicate | Creates a copy of the registration | | Unbind gateway | Detaches the asset from a broker gateway. Unavailable when there is no binding | | Delete | Removes the asset | The arrow icon expands the card to show additional information. ## Folders The right-hand panel organizes assets in two views: | View | What it is | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | **Asset Folders** | The structure you build, starting from the `DEFAULT` root. Group by purpose, environment, client, or any criterion your operation uses | | **Type Folders** | Automatic grouping by platform type, useful for finding a device by technology | Clicking a folder **filters the list**. The active filter appears as a marker above the list — `Folder: DEMO` — with an `x` to remove it and **Clear all** to drop every filter at once. ## The details panel Five tabs: | Tab | Contents | | -------------------- | -------------------------------------- | | **Basic** | The asset's registration data | | **Logins** | Credentials associated with the asset | | **Authorized users** | Users and groups permitted to reach it | | **Asset sessions** | History of sessions on this asset | | **Commands** | Commands executed in those sessions | **Basic** carries: Name, Type (category and platform, such as `Host/Windows`), Address, Platform, Protocols with the effective ports, Domain, Active, creation and update dates, Creator, and Description. {% hint style="warning" %} The protocols and ports shown here come from the asset's **platform**. To change the default for every asset of a platform, use **Sync protocols to assets** on the Platforms screen — editing one asset does not move the others. {% endhint %} Three quick-action blocks sit below the tabs: * **Quick update** — the **Active** switch, **Refresh hardware info** to update the hardware inventory, and **Test connectivity** * **Node** — files the asset in a folder * **Tags** — labels used later to filter the list ## Common errors | Symptom | Cause | Fix | | ----------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------- | | The asset is registered but sessions fail | The platform does not offer the protocol you are trying | Check **Protocols** under Basic, and the platform | | A category is missing from the list | No asset belongs to it | Groups appear only when populated | | Test Connection fails on a reachable host | Wrong port, or no credential to test with | Compare the effective port against the host, then check the account | | **Unbind gateway** is greyed out | The asset has no gateway binding | Expected. Nothing to undo | ## Related pages * [Platforms](/pam/administration/assets/platforms) — where protocols and ports come from * [Folders and tags](/pam/administration/assets/folders-and-tags) * [Discover assets on the network](/pam/administration/assets/discovery) * [Managed accounts](/pam/administration/accounts/managed-accounts) # Discover assets on the network Find assets automatically — from a cloud provider account or by scanning an IP range — and let sync policies file them into the inventory. ## What this is and when to use it Discovery registers a **discovery account** — a cloud provider, a virtualization platform, or a local network segment — and then finds the assets behind it. **Sync policies** decide what happens to each asset found: which platform it gets, which folder of the inventory it lands in, and how it is named. Use it when onboarding an environment, and keep it scheduled afterwards so that machines created outside the solution do not stay outside the inventory. The screen has three tabs: | Tab | What it does | | ------------------- | ----------------------------------------------------------- | | **Accounts** | Lists and manages the discovery accounts already registered | | **Sync policy** | The rules that classify discovered assets | | **Select provider** | The provider catalog, used to register a new account | ## Before you start * For a cloud provider, credentials with permission to list instances. * For a LAN scan, the IP range and a port that responding hosts will have open. * An idea of how you want assets filed — at least one sync policy should exist before the first synchronization, or everything lands in the default. ## Supported providers | Provider | Type | | -------------------- | --------------------------------- | | AWS | Public cloud | | Azure | Public cloud | | Google Cloud | Public cloud | | Volcengine | Public cloud | | Ucloud uhost | Public cloud | | Huawei Cloud | Public cloud | | Huawei Private Cloud | Private cloud | | VMware | Virtualization | | OpenStack | Private cloud | | Nutanix | Hyperconverged infrastructure | | **LAN** | Local network, by IP segment scan | ## Steps — scanning an IP range 1. Open **Environment › Discover** and go to **Select provider**. 2. Click **+** on **LAN**. A three-step wizard opens in a side panel. 3. **Basic** — give the account a **Name**. **Platform** is filled in as *LAN* and is read-only. 4. **LAN** — fill the **Attrs**: * **IP segment** — the range in CIDR notation, `10.0.30.0/24` for example. Press Enter to add more than one segment * **Test port** — the port used to confirm an address responds, `22` for SSH * **Test timeout** — how long to wait for each address, in seconds * **Hostname prefix** — prepended to the name of every asset found 5. **Other** — an optional **Description**. 6. Click **Confirm**. 7. Back on **Accounts**, select the new card and click **Sync**. ## What you should see ![The Discover screen, listing the registered discovery accounts](https://1085357737-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7xzJyi9JVzRwnV6JzUho%2Fuploads%2Fgit-blob-b55964a35e46df218bcc5d854266ca552918bba9%2Fdiscover.png?alt=media) **1** How many discovery accounts exist. **2** The provider catalog, where a new account is registered. The account card shows two counters: **REGION**, how many regions the synchronization covers, and **ASSET**, how many assets have been found. After a run, the **Synchronization history** tab records the execution and **Synchronize instance** lists the instances found. ## How to verify it worked 1. Open **Environment › Assets**. 2. The discovered hosts must be there, in the folder the sync policy assigned, on the platform it assigned, named as its hostname policy dictates. 3. If assets were found but did not reach the inventory, check **Release assets** in the account's **Quick update** — with it off, synchronized assets are not released automatically. Finding instances and filing them are two different things. The counters prove the first; only the asset list proves the second. ## Sync policies Policies are evaluated **in priority order** and act on the assets that match their conditions. {% hint style="warning" %} Priority runs from **1 to 100**, default **50**, and **the lower the number, the higher the priority**. The policy with the smallest number is evaluated first. {% endhint %} ### Creating a policy On the **Sync policy** tab, click **Create**. The wizard has four steps. **1. Basic** — the **Name** and the **Priority**. **2. Condition** — which assets the policy reaches. * **Relationship conditions** — **And** applies the action only when every condition matches; **Or** applies as soon as one does * **Condition** — each line combines three fields, added with **Add**: * **Attribute name** — *Instance name*, *Instance platform name*, or *Instance address* * **Match** — the comparison operator * **Attribute value** — the value compared against **3. Action** — what is applied to matching assets. * **Resource type** — what to assign: *Platform*, *Node*, or the naming policy * **Resources** — the specific value for that type The built-in policy shows the typical shape: it sets the **Platform**, the destination **Node** in the inventory, and the hostname policy — which decides whether the asset is named after the instance, or after the instance combined with part of its IP address. **4. Other** — a free-text **Description**. ## Field reference ### Discovery account — Quick update | Field | What it does | | ------------------ | --------------------------------------------------------------------------------- | | IP type | Whether synchronization uses the asset's private or public IP | | Release assets | Whether synchronized assets are released into the inventory automatically | | Manually execution | Runs a synchronization on demand (**Execute**) or adjusts the schedule (**Edit**) | ### LAN account | Field | What it does | | --------------- | --------------------------------------------------------------- | | IP segment | The range to scan, in CIDR. Required. Multiple segments allowed | | Test port | The port used to confirm an address responds. Required | | Test timeout | Seconds to wait per address. Required | | Hostname prefix | Prefix applied to the name of every discovered asset. Required | ### Sync policy | Field | What it does | | ----------------------- | ---------------------------------------------------------------- | | Priority | 1 to 100, default 50. Lower is evaluated first | | Relationship conditions | **And** requires every condition; **Or** requires one | | Attribute name | *Instance name*, *Instance platform name*, or *Instance address* | | Resource type | *Platform*, *Node*, or the naming policy | ## Related pages * [Asset inventory](/pam/administration/assets/inventory) * [Platforms](/pam/administration/assets/platforms) — what the policy assigns to each discovered asset * [Folders and tags](/pam/administration/assets/folders-and-tags) * [Collect accounts from an asset](/pam/administration/accounts/discovery-of-accounts) — the next step after finding the host # Platforms What a platform defines, how the list is organized, and a description of every built-in platform for hosts, databases, network devices, cloud, and web. A platform is the **technical model of an asset**. It tells the solution what technology it is dealing with and, from that, which access protocols are available, on which ports, whether the connection may pass through a gateway, and whether switching accounts after login is allowed. Every registered asset belongs to a platform. It is the platform that knows a Windows server can be reached over RDP on 3389 and WinRM on 5985, while an Oracle database is reached over the `oracle` protocol on 1521. ## How the list is organized ![The Platforms screen, with the category groups and the details pane](https://1085357737-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7xzJyi9JVzRwnV6JzUho%2Fuploads%2Fgit-blob-93e68df45220d7b824b4a02281e6156c38497dad%2Fplatforms.png?alt=media) **1** Cards are grouped by category, with the count of each. **2** Each protocol with its default port, inherited by assets of this platform. **3** How many assets use the platform. **4** Quick update: Gateway enabled, Enabled su, and Sync protocols to assets. Platforms appear as **cards grouped by category**, each group under a collapsible header showing the category name and how many platforms it holds — `HOST 8`, for example. Each card shows: * the platform **name** and a badge with its **type** (`LINUX`, `UNIX`, `WINDOWS`) * the enabled **protocols**, each with its default port (`SSH: 22`, `RDP: 3389`) * **DEVICES** — how many assets use that platform * the **BUILT-IN** badge, when the platform ships with the product Built-in platforms can only be **duplicated**. Platforms you create also show edit and delete icons. ## The details pane Selecting a platform opens a pane on the right with the name, the protocols as badges, a **Sync protocols to assets** button, and four tabs: | Tab | Contents | | --------------- | ----------------------------------------- | | **Detail** | The *Quick update* and *Protocols* blocks | | **Devices** | Assets using this platform | | **Automations** | Automations that apply to it | | **Activities** | Change history | **Quick update** holds the three most-used settings: | Setting | What it does | | ------------------------ | --------------------------------------------------------------------------- | | Gateway enabled | Allows connections to this platform to pass through a gateway | | Enabled su | Allows switching accounts after login — elevating to `root`, for example | | Sync protocols to assets | Pushes the protocol configuration to every asset already using the platform | The **Protocols** block lists each protocol with its port, which can be changed, and opens advanced settings from the **...** menu. {% hint style="warning" %} The port set here is the **default inherited** by assets of that platform. Changing it does not affect assets already registered until you use **Sync protocols to assets**. {% endhint %} ## Built-in platforms ### Host Physical and virtual servers. The largest category, because it covers three operating-system families. | Platform | Type | Default protocols | When to use it | | ----------------- | ------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | **Linux** | Linux | SSH 22 · SFTP 22 · TELNET 23 · VNC 5900 · RDP 3389 | Linux distributions in general. The most used platform in a typical environment | | **Gateway** | Linux | SSH 22 · SFTP 22 · TELNET 23 · VNC 5900 · RDP 3389 | Machines acting as jump hosts. Same base as Linux, kept separate so the host's role is clear in the inventory | | **Unix** | Unix | SSH 22 · TELNET 23 · VNC 5900 · RDP 3389 | Generic Unix systems | | **AIX** | Unix | SSH 22 · TELNET 23 · VNC 5900 · RDP 3389 | IBM Unix, common in large environments | | **BSD** | Unix | SSH 22 · TELNET 23 · VNC 5900 · RDP 3389 | FreeBSD, OpenBSD, and derivatives | | **macOS** | Unix | SSH 22 · TELNET 23 · VNC 5900 · RDP 3389 | macOS workstations and servers | | **Windows** | Windows | RDP 3389 · WinRM 5985 · SSH 22 · VNC 5900 | Windows servers and workstations. RDP serves graphical access, WinRM serves automations | | **Windows-RDP** | Windows | RDP 3389 · WinRM 5985 · SSH 22 · VNC 5900 | For hosts that require classic RDP negotiation, without TLS | | **Windows-TLS** | Windows | RDP 3389 · WinRM 5985 · SSH 22 · VNC 5900 | For hosts that require RDP over TLS | | **RemoteAppHost** | Windows | RDP 3389 · WinRM 5985 · SSH 22 | The host that publishes remote applications. It runs the applets; it is not an ordinary access target | | **Other** | Other | SSH 22 · SFTP 22 · TELNET 23 · VNC 5900 · RDP 3389 | Hosts that fit none of the families above | {% hint style="info" %} The three Windows variants exist because RDP security negotiation differs between server versions and configurations. When a graphical connection fails during negotiation, switching the asset between **Windows**, **Windows-RDP**, and **Windows-TLS** is the first thing to try. {% endhint %} ### Database Databases reached through the web console or a native client. | Platform | Default protocol | Note | | -------------- | ---------------- | -------------------------------------------------------- | | **Oracle** | oracle 1521 | | | **MySQL** | mysql 3306 | | | **MariaDB** | mariadb 3306 | A MySQL fork, treated as its own platform | | **PostgreSQL** | postgresql 5432 | | | **SQLServer** | sqlserver 1433 | Microsoft SQL Server | | **MongoDB** | mongodb 27017 | Document database | | **Redis** | redis 6379 | Versions before 6 | | **Redis6+** | redis 6379 | Version 6 and later, which have their own users and ACLs | | **ClickHouse** | clickhouse 9000 | Columnar analytical database | | **DB2** | db2 50000 | IBM Db2 | | **Dameng** | dameng 5236 | DM database | {% hint style="info" %} **Redis** and **Redis6+** are separate because Redis gained per-user authentication in version 6. Choosing the wrong one prevents login with a named credential. {% endhint %} ### Device Network equipment, reached by command line. All use **SSH 22** and **TELNET 23**. | Platform | When to use it | | ------------ | ---------------------------------------------------------- | | **General** | A generic network device, when no specific platform exists | | **Cisco** | Cisco equipment | | **Huawei** | Huawei equipment | | **H3C** | H3C equipment | | **Fortinet** | Fortinet appliances | The difference between them is terminal handling and command recognition, which affects command auditing and command inspection for each vendor. ### Cloud | Platform | Default protocol | When to use it | | ------------------ | ---------------- | -------------------------------------------------------------- | | **Kubernetes** | k8s 443 | Kubernetes clusters, with panel access through the web console | | **Vmware-vSphere** | http 80 | VMware vSphere virtualization | ### Web | Platform | Default protocol | When to use it | | ----------- | ---------------- | ----------------------------------------------------------------------------------- | | **Website** | http 80 | Web applications opened in the browser with the credential injected by the solution | ### GPT | Platform | Default protocol | When to use it | | ----------- | ---------------- | ----------------------------------------- | | **ChatGPT** | chatgpt 443 | Audited access to a generative AI service | ## Custom platforms When no built-in platform fits, create one with **Create**, or duplicate an existing platform, which keeps its protocol configuration as a starting point. Custom platforms are identified by the **absence of the BUILT-IN badge** and can be edited and deleted freely. Duplicating a built-in platform is the recommended path when you only need to adjust ports or disable a protocol while keeping the rest of the behavior. ## Related pages * [Core concepts](/pam/get-started/core-concepts) — how platforms relate to assets and accounts * [Asset inventory](/pam/administration/assets/inventory) * [Connection methods](/pam/administration/sessions/connection-methods) # Folders and tags Build the asset folder tree, file assets into it, and use folders as the target of rules — plus what tags do that folders do not. ## What this is and when to use it Folders and tags are the two ways of grouping assets, and they are not interchangeable. A **folder** — called a **Node** wherever a form asks for one — is a position in a hierarchy you build. Its value is that rules can point at it: an authorization, a rotation task, or a discovery policy can name a folder instead of a list of assets, and every asset in that folder is covered, including the ones added tomorrow. A **tag** is a flat `key: value` label. An object can carry several, and tags cut across the hierarchy — `env: prod` can sit on assets in six different folders. Tags filter lists; with few exceptions they do not grant anything. | | Folders (Nodes) | Tags | | --------------------- | ---------------------------------------------------------- | -------------------------------------------- | | Shape | A tree, from the `DEFAULT` root | Flat `key: value` labels | | Built by | You, per environment, client, or purpose | You, ad hoc, as you register objects | | Used as a rule target | Yes — authorizations, automation tasks, discovery policies | No | | Used to filter lists | Yes | Yes | | Applies to | Assets | Assets, accounts, templates, users, gateways | {% hint style="info" %} [Asset inventory](/pam/administration/assets/inventory) describes the folder panel as a filtering device — the two trees, the `Folder: DEMO` marker, **Clear all**. This page is about building the structure and using it as more than a filter. {% endhint %} Two trees exist side by side in the panel, and only one of them is yours: * **Asset Folders** — the structure you build, from the `DEFAULT` root. * **Type Folders** — automatic grouping by platform type. It is a view, not a place. You cannot file anything into it and nothing you do there changes an asset. ## Before you start * A criterion for the hierarchy, chosen before you start creating folders — environment, client, business unit, or criticality. Whatever it is, it should be the thing your authorizations will want to name. * The **SYSADMIN** profile. Choose the criterion by asking what a future authorization will need to grant. A tree organized the way your access rules think is worth more than one organized the way your rack is wired. ## Steps 1. Open **Environment › Assets**. The **Asset Folders** tab of the right-hand panel holds the tree, starting from `DEFAULT`. 2. Build the structure you need under `DEFAULT`. The counter at the top of the panel reports how many folders exist. 3. File each asset: open the asset's details and use the **Node** block to place it in a folder. On the create form, the **Node** field does the same thing at registration time. 4. Add **Tags** from the same details panel for the cross-cutting labels — owner, environment, criticality. 5. For assets that arrive by themselves, set the folder in a discovery **sync policy** instead of by hand: an action with resource type **Node** files every newly discovered asset that matches the policy's conditions. See [Discover assets on the network](/pam/administration/assets/discovery). ## What folders are used for Filtering the list is the least of it. | Where | How the folder is used | | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | [Authorizations](/pam/administration/access/authorizations) | The **Nodes** field grants a whole folder — for example `/OFFICE`. Assets filed there later are covered without editing the rule | | [Rotate credentials](/pam/administration/accounts/rotation) and push tasks | **Assets or Nodes** targets a folder, so the task follows the folder's contents | | [Discovery](/pam/administration/assets/discovery) sync policies | An action of resource type **Node** decides where a newly found asset lands | | [Managed accounts](/pam/administration/accounts/managed-accounts) | The **Asset tree** in the side panel filters accounts by asset group | | A user's **Authorized assets** tab | The tree filters the assets that user can actually reach | | The user's own access list | Users filter their devices by folder, alongside **Favorites** | This is the reason to keep the tree tidy. A folder named in three authorizations and two rotation tasks is a piece of your access policy, not a convenience for browsing. ## What tags are used for * **Filtering.** Asset, account, and template lists each carry a **Tags** control that filters by the labels attached. * **Feature input, occasionally.** Tags are not always inert: the publishing machine for a virtual access application is chosen at random by default, and a tag in the asset's configuration pins a specific machine instead. Treat a tag as data the product may read, not only as a note to yourself. **Sysadmin › Others › Tags** lists the tags that exist in the tenant. It is worth opening after a bulk import. {% hint style="warning" %} On import, **a tag that does not exist is created automatically**. A typo does not fail — it silently creates a second, nearly identical tag, and the filter you build later quietly misses half the assets. Check the tag list after any bulk import of assets or users. {% endhint %} Tags are written as `key: value` pairs, and in an import file they are a JSON array of strings: `["env: prod", "owner: dbteam"]`. ## How to verify it worked Filing an asset is easy to confirm and proves nothing. Verify that the **folder scope** works, because that is what you are actually relying on: 1. Create an authorization whose target is a folder rather than a list of assets, and grant it to a test user. 2. Confirm the test user sees the assets currently in that folder. 3. Now file a **new** asset into the same folder, and change nothing else. 4. The test user must see the new asset without any edit to the authorization. If they do not, the rule is targeting assets individually and the folder is decorative. For tags, filter a list by the tag you just applied and confirm the asset appears — then confirm no near-duplicate of that tag exists in **Sysadmin › Others › Tags**. ## Common errors | Symptom | Cause | Fix | | ---------------------------------------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------- | | The asset count on a folder looks wrong | Counts are refreshed by a periodic task, not on every change | Trust the filtered list, not the badge. The count catches up on the next run | | A new asset in a granted folder is not visible to the user | The authorization names assets individually instead of the folder | Change the rule to target the **Node** | | A tag filter returns fewer assets than expected | A near-duplicate tag was created by a typo during import | Check **Sysadmin › Others › Tags** and consolidate | | Assets appear in a folder you never created | That is **Type Folders**, the automatic grouping by platform | Switch to the **Asset Folders** tab | | Reorganizing the tree breaks access | An authorization or a task named a folder you moved or renamed | Check which rules name a folder before restructuring it | | A rotation task suddenly covers more hosts | It targets a folder, and assets were filed into it | Expected. Folder-scoped tasks follow the folder | ## Field reference | Item | Where | What it is | | -------------------- | ---------------------------------------------- | ---------------------------------------------- | | Asset Folders | The panel on **Environment › Assets** | The tree you build, from the `DEFAULT` root | | Type Folders | The same panel | Automatic grouping by platform type. Read-only | | Node | Asset create form, and the asset details panel | Files the asset in the folder tree | | Nodes | Authorization form | Grants a whole folder | | Assets or Nodes | Rotation and push tasks | Targets individual assets, folders, or both | | Resource type = Node | Discovery sync policy action | Files newly discovered assets into a folder | | Tags | Asset, account, template, and user forms | `key: value` labels. Several per object | | Tags | List toolbars | Filters the list by tag | ## Related pages * [Asset inventory](/pam/administration/assets/inventory) — the folder panel and how filtering behaves * [Discover assets on the network](/pam/administration/assets/discovery) — filing new assets automatically * [Authorizations](/pam/administration/access/authorizations) — granting a folder instead of a list * [Rotate credentials](/pam/administration/accounts/rotation) — folder-scoped automation targets * [Platforms](/pam/administration/assets/platforms) — what **Type Folders** groups by # Accounts | Page | What it covers | | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Managed accounts](/pam/administration/accounts/managed-accounts) | Register, test, and maintain the credentials the solution uses to authenticate on your assets. | | [Account templates](/pam/administration/accounts/account-templates) | Reusable account definitions, so the same credential can serve many assets without being registered one by one. | | [The credential vault](/pam/administration/accounts/vault) | What the vault holds, the three ways a secret leaves it, how every retrieval is recorded, and how the vault is backed up under split custody. | | [Vault entries and folders](/pam/administration/accounts/vault-entries) | Storing credentials that no automation manages, organising them in folders, sharing them with named permissions, and revealing a secret behind MFA. | | [Password generation policy](/pam/administration/accounts/password-policy) | The rules that decide how a generated secret is composed — length, character classes, and excluded characters — and how they differ from the password rules that apply to console users. | | [Rotate credentials](/pam/administration/accounts/rotation) | Rotate passwords and SSH keys automatically or on demand, and what to watch for when the credential is a domain account. | | [Collect accounts from an asset](/pam/administration/accounts/discovery-of-accounts) | Collect the accounts that already exist on an asset, classify the privileged ones, and bring them under management. | # Managed accounts Register, test, and maintain the credentials the solution uses to authenticate on your assets. ## What this is and when to use it A managed account is a credential on an asset that the solution stores and supplies on the user's behalf. **Accounts › Accounts** is where they are registered, tested, edited, and removed. There are two kinds, and they behave differently: | Kind | Where it comes from | Behavior | | ------------------- | ------------------------------------------------------ | ------------------------------------------ | | **Common account** | Registered by hand, or brought in by a collection task | Static — it exists until you remove it | | **Virtual account** | Created by an authorization rule at connection time | Dynamic — it exists because a rule says so | This page is about common accounts. Virtual accounts are configured on the [authorization](/pam/administration/access/authorizations) that creates them. ## Before you start * The asset already registered under **Environment › Assets**. * The credential itself — password, SSH key, token, access key, or API key. * **MFA enabled** on your own account to reveal a secret or export accounts. ## Steps 1. Open **Accounts › Accounts**. 2. Click **Create**. 3. Select the **asset** the credential belongs to. 4. Fill the **username** and the secret — password, SSH key, or another supported type. 5. Set **su/sudo** if the account must elevate after login. 6. Mark **Privileged** if the account holds administrative rights on the target. 7. Save. 8. Select the account and click **Test selected** to confirm it authenticates. {% hint style="info" %} To attach the same credential to many assets at once, use **Add from template** instead of registering it repeatedly. See [Account templates](/pam/administration/accounts/account-templates). {% endhint %} ## What you should see ![The Accounts screen, listing the credentials registered against each asset](https://1085357737-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7xzJyi9JVzRwnV6JzUho%2Fuploads%2Fgit-blob-ba45857b0b023400a382b80991e839c30ddc919e%2Fmanaged-accounts.png?alt=media) **1** How many accounts the current filter returns. **2** One account row, with its asset and the date it was last updated. The account appears in the list against its asset, with the date of the last update. The side panel offers two trees to filter by — **Asset tree**, the folder structure, and **Type tree**, by platform category. ## How to verify it worked Registering a credential does not prove it works on the target. 1. Select the account and run **Test connectivity** from its **Quick update** panel, or **Test selected** from the toolbar. 2. Open a session to the asset using that account. A successful login is the only proof that the stored secret and the target agree. 3. If the account is meant to be privileged, confirm it carries the **Privileged** marking. An account that saves cleanly and fails the connectivity test is the normal result of a wrong password or a missing protocol — not of a wrong registration. ## Toolbar | Control | What it does | | ----------------- | ------------------------------------------------ | | Create | Registers an account by hand | | Add from template | Brings the credential in from a template | | Test selected | Tests connectivity of the selected accounts | | Clear secret | Wipes the stored secret of the selected accounts | | Update selected | Bulk-edits the selected accounts | | Delete selected | Removes them | | Upload / Export | Bulk import and export, CSV or XLSX | | Tags | Filters by tag | | List preferences | Chooses the visible columns | ## Account details Clicking an account's name opens its page, with two tabs: * **Basic** — ID, Name, Username, Secret type, Tags, Switch from, Asset, Version, Source and Source ID, Connectivity, Organization, LDAP account, Active, Has secret, creation and update dates, Created by, Description * **Activities** — the change history of this account The **Quick update** panel on the right holds the three actions used most: **Active**, **Privileged**, and **Test connectivity**. ## Password history Every stored secret is versioned. The account keeps its previous values with the date and time each was recorded, so a credential changed outside the solution can still be recovered from the version that was in force. ## Common errors | Symptom | Cause | Fix | | ---------------------------------------------------------- | ---------------------------------------------------- | -------------------------------------------------------------------- | | Connectivity test fails | Wrong secret, or no management protocol on the asset | Check the secret, then confirm the asset has SSH or WinRM registered | | The account cannot be rotated | The asset's only protocol is RDP | Rotation needs a management channel. Add WinRM or OpenSSH on Windows | | The secret cannot be revealed | MFA is not enabled on your account | Enable MFA and retry | | The same credential exists on many assets and drifts apart | It was registered per asset instead of as a template | Move it to a template | ## Related pages * [Account templates](/pam/administration/accounts/account-templates) * [The credential vault](/pam/administration/accounts/vault) * [Rotate credentials](/pam/administration/accounts/rotation) * [Collect accounts from an asset](/pam/administration/accounts/discovery-of-accounts) * [Authorizations](/pam/administration/access/authorizations) — where virtual accounts are defined # Account templates Reusable account definitions, so the same credential can serve many assets without being registered one by one. ## What this is and when to use it A template is a **reusable account definition**. Register the credential once, link it to as many assets as need it, and maintain it in one place instead of in each asset. The case that makes it obvious: three Active Directory instances that share the same *Domain Admin* login. Registering that login three times means three places to update and three chances to forget one. As a template, it is registered once and linked to all three at the moment each asset is created. {% hint style="warning" %} A template is not a copy of a password — it is the **source** of one. Read the [synchronization](#synchronization) section before editing a template that is already in use, because the change does not necessarily reach the assets on its own. {% endhint %} ## Before you start * An administrator profile. The screen is restricted to administrators. * **MFA enabled** on your own account if you intend to reveal a secret or export accounts — both actions require it. ## Steps — creating a template 1. Open **Accounts › Templates** and click **Create**. 2. **Name** — how you will recognize the credential. Required. 3. **Username** — the user name used to authenticate on the assets. 4. **Privileged** — tick it when the account holds administrative privilege on the target, such as `root` or `administrator`. 5. **Secret type** — Password, SSH Key, Token, Access Key, or API Key. 6. **Secret strategy** — whether the secret is specified by you or generated randomly. 7. Save. ## What you should see ![The Templates screen](https://1085357737-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7xzJyi9JVzRwnV6JzUho%2Fuploads%2Fgit-blob-8bfc62b64d5bddb5b8e3bcd2e1afde02a8fa267b%2Faccount-templates.png?alt=media) **1** How many templates exist. **2** Create, which registers a template by hand. The template appears in the list. The **Auto push** column tells you whether edits will be propagated to the linked assets automatically — this is the column that decides whether you need to synchronize by hand. ## Synchronization When **Auto push** is not enabled for a template, editing it changes the template and nothing else. The linked assets keep the previous credential until you synchronize. 1. Open **Accounts › Templates** and click the template's name. 2. Go to the **Accounts** tab. The table lists every asset the template is linked to. **View** in the Actions column reveals the current password for that asset — this requires MFA. 3. Click **Sync**. A window opens with the task log, showing success or failure per asset. The task is finished when it reports `succeeded`. Read the log per asset. A task can finish while individual assets failed, and those assets keep the old credential. ## How to verify it worked 1. Open the template's **Accounts** tab and confirm every intended asset is listed. 2. After a synchronization, open one of the assets and confirm the credential there matches the template. 3. Open a session to that asset using the account. A successful login is the only proof that the target and the vault agree. ## Common errors | Symptom | Cause | Fix | | ------------------------------------------------------------ | -------------------------------------------------------------------------- | --------------------------------------------------------------- | | Edited the template and nothing changed on the assets | **Auto push** is off | Run **Sync** from the template's **Accounts** tab | | Sync reported success but one asset still fails | That asset failed inside the run | Read the task log per asset, not just the final status | | **View** does not reveal the secret | MFA is not enabled on your account | Enable MFA, then retry | | Export is greyed out | No account is selected, or MFA is not enabled | Select at least one account and enable MFA | | Import rejected | The file is not in the expected CSV or XLSX layout | Export first and use that file as the model | | A rotated domain credential works everywhere except one host | Rotation does not update the template, and that host was linked afterwards | See [Rotate credentials](/pam/administration/accounts/rotation) | ## Toolbar | Control | What it does | | ------- | ----------------------------------------------------------------------------------- | | Create | Registers a template by hand | | Tags | Filters templates by tag | | Upload | Imports accounts from CSV or XLSX, creating or updating in bulk | | Export | Exports the visible accounts to CSV. Requires MFA and at least one selected account | | Refresh | Reloads the table | | Gear | Chooses which columns the table shows | ## Field reference | Column | What it means | | ------------------------------ | ---------------------------------------------------------------- | | Name | The template's identifying name | | Username | The user name used to log in | | Secret type | Password, SSH key, token, access key, or API key | | Privileged | Whether the account is privileged on the asset it is attached to | | ID | Unique identifier | | Tags | Labels attached to the template | | Secret strategy | Whether the secret is random or specified | | Platforms | The platform attached to the template | | Switch from | Login redirection, when there is one | | Organization / Organization ID | The tenant the template belongs to | | Active | Whether the template may be used to log in to assets | | Auto push | Whether editing the template propagates the change automatically | | Date created / Date updated | Creation and last change | | Created by | Who created or imported it | | Description | Free text | ## Related pages * [Managed accounts](/pam/administration/accounts/managed-accounts) * [Rotate credentials](/pam/administration/accounts/rotation) — and why rotation never updates the template * [Multi-factor authentication](/pam/administration/identities/mfa) — required to reveal and export secrets # The credential vault What the vault holds, the three ways a secret leaves it, how every retrieval is recorded, and how the vault is backed up under split custody. ## What this is and when to use it The vault holds the secrets of every managed account: the password, SSH key, token, access key or API key that authenticates to the target. It is the centre of the product, and the reason the other pages exist. Assets say where to connect, authorizations say who may, rotation says how often the secret changes, and the vault is what all three are protecting. Its working principle is that **a secret is used far more often than it is seen**. The default path opens a session without the secret ever reaching the person using it, and the paths that do reveal it are separately permitted and separately recorded. ## What the vault holds One secret per managed account, of one of these types: | Secret type | Typical use | | ----------- | ------------------------------------------ | | Password | Windows, Linux, network devices, databases | | SSH key | Linux and Unix hosts, network devices | | Token | APIs and services | | Access key | Cloud provider accounts | | API key | Application integrations | Each secret carries a **version**. Rotating an account does not overwrite its history: the previous values are retained, which is what lets you answer "which credential was valid on the day of the incident" months later. See [Rotate credentials](/pam/administration/accounts/rotation). The account inventory reports which accounts actually hold a secret, alongside whether each one is privileged and whether automatic rotation reaches it. That report is the shortest answer to "is the vault complete", and it exposes the accounts that were registered but never had a credential stored. See [Reports](/pam/administration/audit/reports). ## The three ways a secret leaves the vault | Path | What the user gets | When to allow it | | ----------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | **Use it** | A session opens, authenticated with the secret. The user never sees it and cannot copy it | The default. Should cover almost every case | | **Copy it** | The secret goes to the clipboard without being displayed | A client the console cannot drive | | **View it** | The secret is displayed on screen | The exception. An emergency, or a tool that needs the value typed by hand | Which of the three a user gets is decided on the authorization, not on the account, so the same account can be usable without being viewable by one team and fully visible to another. See [Authorizations](/pam/administration/access/authorizations). {% hint style="info" %} An authorization can also grant an account the user is not meant to know at all. **Manual account** asks the user for credentials at connection time and stores nothing; **Anonymous account** connects with no credential. Neither involves the vault, and both are useful for assets whose credentials must stay outside it. {% endhint %} ## Every retrieval is recorded Reading a secret is an audited event in its own right, separate from opening a session. The record carries the date, who or what asked for it, which account was read, the source address, and the action. The same record covers applications: when a script or a scanner fetches a credential through [application-to-application access](/pam/administration/integrations/application-to-application), the retrieval lands in the same trail as a person clicking *view*. That is what makes "who has read this credential, ever" a question with a complete answer. **Credential retrieval** is one of the operational reports, and it is cited as evidence by six of the seven compliance packages. See [Compliance mappings](/pam/reference/compliance-mappings). ## Backing up the vault ![The Backup accounts screen, with a scheduled task and its two custodians](https://1085357737-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7xzJyi9JVzRwnV6JzUho%2Fuploads%2Fgit-blob-bdd2616640400ec243cd05f861732e43820c8b67%2Fvault-backup.png?alt=media) **1** The task, named for what it produces. **2** The schedule, as a crontab expression. **3** Custodian A. **4** Custodian B. With both set, the key is split and neither half opens the backup alone. The backup task exports the credentials encrypted and delivers them by email, SFTP, or webhook. | Aspect | Detail | | ------------- | ----------------------------- | | Algorithm | AES-256-CBC | | Key splitting | Shamir Secret Sharing, 2 of 2 | | Format | Encrypted ZIP or JSON | ### Before you start * An email server configured, if the delivery is by email. * A master password set for opening the vault. ### Steps 1. Open **Accounts › Automations › Backup account**. 2. Click **Create** and set the **Name** and **Type**. 3. Choose the **Backup type**: **Email**, **SFTP**, or **Webhook**. 4. Under **Password divided**, set **Custodian A** and **Custodian B**. 5. Set the schedule. 6. Save, and follow the runs under the executions history. {% hint style="warning" %} **The split only happens with two custodians.** If both recipient A and B are set, the ciphertext is split in two parts and both are needed to decrypt. If only one recipient is set, **the key is not split** — that single recipient can open the whole vault alone. This is the setting people get wrong, and the failure is silent: the backup works either way. {% endhint %} ### How to verify it worked 1. Open the task's execution history and confirm the run succeeded. 2. Confirm each custodian received their part — two parts, if you configured two. 3. Restore into a test instance. A backup that has never been restored is a hypothesis, not a backup. ## Emergency access — break-glass The solution allows an emergency access account for contingency: an authorized custodian, after two-factor authentication, can read any credential in the vault. **How it works** * Emergency access requires two-factor authentication, separate from the normal login, before any credential is revealed. * Once authenticated, the custodian can retrieve any credential in the vault, keeping operations running when approvers are unavailable, during an incident, or in disaster recovery. * It combines with the dual-custodian model, where the key parts are held by different people, tightening control over emergency use. **Audit and alerting** Every use of the emergency account is written to the audit trail — who, when, and which credentials were accessed — and can raise specific alerts, so that any break-glass use is reviewed immediately. {% hint style="danger" %} Keep the emergency account outside the reach of automatic credential rotation. An automation that rotates the one credential you rely on during an incident defeats its purpose. {% endhint %} ## How to verify the vault is doing its job Four checks, in the order that finds problems fastest: 1. **Open a session on a managed account and confirm nothing was revealed.** The session should authenticate without the secret appearing anywhere in the interface. This is the behaviour everything else depends on. 2. **Run the account inventory report** and look at the *has secret* column. An account registered without a credential looks managed from the asset list and is not. 3. **Read one secret deliberately**, then find that read in the credential retrieval report. If the read is not in the report, the trail is incomplete and no other control can be trusted. 4. **Rotate one account and confirm the previous version is still retained.** Retention of prior versions is what answers an incident question after the fact. ## Common errors | Symptom | Cause | Fix | | ------------------------------------------------ | ----------------------------------------------------------- | ------------------------------------------------------------------- | | A user sees the secret when they should not | The authorization grants *view*, not only *use* | Remove the view permission on the authorization, not on the account | | An account is in the inventory but sessions fail | It holds no secret | Check the *has secret* column and store the credential | | The backup arrives as a single openable file | Only one custodian was configured, so the key was not split | Set both Custodian A and Custodian B | | The backup cannot be decrypted | One of the two parts is missing | Both parts are required. Recover the missing custodian's part | | Email backup never arrives | The email server is not configured | Configure notifications first | | A secret cannot be revealed in the console | MFA is not enabled on the account | Enable MFA | ## Related pages * [Managed accounts](/pam/administration/accounts/managed-accounts) — the accounts whose secrets live here * [Vault entries and folders](/pam/administration/accounts/vault-entries) — credentials kept and shared by hand, which no automation manages * [Rotate credentials](/pam/administration/accounts/rotation) — how a stored secret is changed, and what happens to the previous one * [Authorizations](/pam/administration/access/authorizations) — where use, copy and view are decided * [Application-to-application access](/pam/administration/integrations/application-to-application) — how a script retrieves a secret without a person * [Multi-factor authentication](/pam/administration/identities/mfa) — the second factor that reveal and break-glass require * [Audit trail](/pam/administration/audit/audit-trail) — where every retrieval is recorded # Vault entries and folders Storing credentials that no automation manages, organising them in folders, sharing them with named permissions, and revealing a secret behind MFA. ## What this is and when to use it Not every credential belongs to a managed asset. A certificate authority login, a supplier portal, a registrar, a licence account: things a team needs, that no rotation job can reach, and that otherwise end up in a spreadsheet. **Vault** holds those. Each credential is an **entry**; entries live in **folders**; and both can be shared with named users and groups under explicit permissions. Revealing a secret requires a second factor, and every entry keeps the history of its previous values. {% hint style="info" %} This is a different store from the secrets of managed accounts. A managed account's credential is held against an asset and is rotated, pushed and used to open sessions; see [The credential vault](/pam/administration/accounts/vault). A Vault entry is held by a person, shared by hand, and never pushed anywhere. Use managed accounts for what the solution connects to, and Vault for everything else the team has to keep. {% endhint %} ## Folders ![The Vault screen, with folders, credentials and the detail pane](https://1085357737-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7xzJyi9JVzRwnV6JzUho%2Fuploads%2Fgit-blob-391988f3befec66e5058a5012381646722037ed7%2Fvault-entries.png?alt=media) **1** How many folders and credentials the vault holds. **2** A folder, with its own count and its private state. **3** A credential shared with someone else. **4** New Credential, which opens the entry form. Every user gets a **Default** folder, created automatically. It cannot be renamed, changed or deleted, and it is where anything without an explicit folder lands. Beyond that, you create folders freely. Two behaviours are worth knowing before you organise anything: * An entry saved without a folder goes to **your** Default folder. * **Deleting a folder does not delete its entries.** They are moved to Default. That is deliberate, and it means a folder deletion is never a credential loss. ## Entries | Field | Required | What it holds | | ------------------- | -------- | ------------------------------- | | Site or application | Yes | The name of the service | | Username | Yes | The login or e-mail | | Password | Yes | The secret. Stored encrypted | | URL | No | Address of the service | | Folder | No | Defaults to your Default folder | | Comment | No | Free note | ## Sharing An entry or a folder is shared with users, with groups, or with both. Each share carries up to four permissions, and they are **cumulative**: | Permission | What it allows | | ------------ | ------------------------------------------------------------------ | | `can_view` | See the folder or entry. **The default when nothing is specified** | | `can_create` | Create entries inside the folder. Only meaningful on a folder | | `can_update` | Edit the entry | | `can_delete` | Delete the entry | Three rules decide what someone can actually do: 1. **`can_update` and `can_delete` imply `can_view`.** You do not have to grant view separately. 2. **Only the owner manages sharing.** Nobody who received a share can re-share it, rename the folder, or change who else has it. 3. **Folder and entry permissions combine, and the more permissive wins.** `can_view` on the folder plus `can_update` on one entry means the person edits that entry and only reads the rest. {% hint style="warning" %} **`can_update` on a folder applies to every entry in it**, including entries added later. Grant it when you mean "this person maintains this folder", not when you mean "this person may fix one password". Note also that changing shares is a **total replacement**: the list you submit becomes the whole set. Sending an empty list removes every share. {% endhint %} ### Who can do what | Action | Owner | `can_view` | `can_create` | `can_update` | `can_delete` | | ------------------------------- | ----- | ---------- | ------------ | ------------ | ------------ | | See the entry in the list | Yes | Yes | Yes | Yes | Yes | | See the entry detail | Yes | Yes | Yes | Yes | Yes | | Reveal the secret, with MFA | Yes | Yes | Yes | Yes | Yes | | Create an entry in the folder | Yes | No | Yes | No | No | | Edit the entry | Yes | No | No | Yes | No | | Delete the entry | Yes | No | No | No | Yes | | See the folder | Yes | Yes | Yes | Yes | Yes | | Create, rename, delete a folder | Yes | No | No | No | No | | Change the folder's sharing | Yes | No | No | No | No | {% hint style="danger" %} **Any level of share can reveal the secret.** `can_view` is enough. There is no permission that grants "see that this entry exists" without also granting the password behind a second factor. Share an entry only with people who may hold the credential itself. {% endhint %} ## Revealing a secret Reading a password in clear is a separate, read-only operation and **requires MFA confirmation**, regardless of the permission that granted access to the entry. Passing the normal login is not enough. ## Password history Every entry keeps its previous values. The history records, for each change: | Field | What it holds | | ------ | -------------------- | | Secret | The previous value | | Date | When it was replaced | | User | Who replaced it | This is what answers "what was this password in March", and it is also how a change made by the wrong person is undone. ## Importing from a spreadsheet Credentials already living in a spreadsheet can be loaded in one pass. 1. Download the import template, as **XLSX** or **CSV**. In the XLSX, the required columns are marked in red and the optional ones in blue. 2. Fill it in. The columns are the entry fields above. 3. Upload the filled file. A folder named in the file that does not exist yet **is created automatically**. A row with no folder goes to Default. Only `.xlsx` and `.csv` are accepted. ## How to verify it worked 1. **Create an entry, share it with one colleague as `can_view`, and ask them to open it.** Confirm they see it, and confirm the reveal asks them for a second factor. 2. **Ask the same colleague to try to edit it.** They should not be able to. This is the check that catches a share granted wider than intended. 3. **Change a password and open the history.** The previous value, the date and your username should be there. 4. **After an import, count the entries** and open one from a folder the file created. A row whose folder name had a typo creates a folder, it does not fail, so a miscount is how you find those. ## Common errors | Symptom | Cause | Fix | | -------------------------------------------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | Someone can edit entries you meant them only to read | They hold `can_update` on the **folder**, which covers every entry in it | Move the permission to the individual entry | | A share you added disappeared | Shares are replaced wholesale, not merged. A later update submitted without it removed it | Resubmit the complete list of shares | | An entry is not in the folder you expected | It was saved without a folder, so it went to your Default | Move it, and set the folder explicitly next time | | Entries survived a folder you deleted | That is the intended behaviour | They are in Default | | The secret will not reveal | MFA is not confirmed, or not configured for the user | See [Multi-factor authentication](/pam/administration/identities/mfa) | | The import is refused | The file is not `.xlsx` or `.csv`, or it is corrupt | Re-export from the template | | A colleague cannot create entries in a folder you shared | `can_view` does not include creating | Grant `can_create` on the folder | ## Related pages * [The credential vault](/pam/administration/accounts/vault) — the secrets of managed accounts, which are a different store * [Managed accounts](/pam/administration/accounts/managed-accounts) — credentials the solution rotates and uses to open sessions * [Multi-factor authentication](/pam/administration/identities/mfa) — the second factor every reveal requires * [Users and groups](/pam/administration/identities/users-and-groups) — who a folder or entry can be shared with # Password generation policy The rules that decide how a generated secret is composed — length, character classes, and excluded characters — and how they differ from the password rules that apply to console users. ## What this is and when to use it Whenever the solution produces a secret for you — on a template set to generate randomly, on a push task that creates accounts, on a rotation task that changes them — it composes that secret from a **password generation policy**: a length and a set of character classes. Two different things in this product are called a password policy, and mixing them up wastes an afternoon: | | Password generation policy | Password rules | | ---------------- | ------------------------------------------------------------------------ | --------------------------------------------- | | Applies to | Secrets the solution **generates** for accounts on your assets | Passwords **console users** type to sign in | | Where it is set | On the account template or the automation task that generates the secret | **System settings › Security › Passwords** | | Who is affected | The target host's local or domain account | Local users of the solution itself | | What it controls | How the generated string is composed | Minimum length, complexity, expiry, and reuse | This page covers both, generation first. If you are here because a rotation failed, you want the generation policy. ## Before you start * The strictest password policy among the **target** hosts. The generated secret has to satisfy the target, not the solution — a policy that is comfortable for the solution and too weak for a Windows domain fails at the moment of the change. * Whether the credential is stored on a template or on the task. The generation policy is set in both places and they are independent. ## Where the generation policy is set | Screen | Field | What it decides | | ------------------------------------------ | ----------------------------------------- | ------------------------------------------------------------------------------ | | **Accounts › Templates** | **Secret strategy** | How the template's secret is produced when the credential is created or pushed | | **Accounts › Automations › Push accounts** | **Password generation policy** (required) | How the secret of each account created on the targets is produced | | **Accounts › Automations › Change secret** | **Password policy** | How the new secret is produced on each rotation | In all three, the choice is the same pair: * **Random generate** — the solution composes the secret from the rules below. * **Specific secret** — you type the value, and the rules do not apply. ## Steps 1. Open the template or the automation task that produces the secret. 2. Set the strategy to **Random generate**. 3. Set the **length**. It is configurable from **4 to 100** characters. 4. Tick the character classes the target requires — uppercase, lowercase, digits, special characters. 5. List any characters to **exclude**. Use this for targets and clients that choke on particular symbols rather than lowering the complexity for everything. 6. Save, and run the task once by hand before trusting a schedule. {% hint style="warning" %} Set the policy to match the **strictest** target in the task's scope, not the average one. A single Windows domain controller in a task otherwise full of Linux hosts sets the floor for the whole task. {% endhint %} {% hint style="info" %} Several accounts in one rotation task all receive the **same** generated secret in a given run. If you need distinct secrets per account, split them into separate tasks. See [Rotate credentials](/pam/administration/accounts/rotation). {% endhint %} ## What you should see The template or task lists its strategy — random or specified — in the **Secret strategy** column. Nothing on that screen tells you whether the generated value was accepted by the targets. ## How to verify it worked 1. Run the task once manually. 2. Open the affected account under **Accounts › Accounts** and check its **password history**. A new version, dated at the run, is proof that a new secret was generated and stored. 3. Read the execution log **host by host**. A task can report success overall while individual hosts rejected the secret, and those hosts keep the old one. 4. Open a session to one of those hosts using the account. A successful login is the only proof that the stored value and the target agree. ## Common errors | Symptom | Cause | Fix | | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | `The password does not meet the password policy requirements` | The generated secret does not satisfy the target's own policy — length, complexity, or password history | Raise the length and tick the missing character classes to match the strictest target | | Some hosts took the new secret, others kept the old one | Those hosts rejected the value, or were unreachable | Read the execution log per host, then retry those hosts | | Two accounts in one task ended up with the same password | Expected — one generated secret per run | Split them into separate tasks | | The rules are set but the secret never changes | The strategy is **Specific secret**, so the rules are ignored | Switch to **Random generate** | | A rotated domain credential works everywhere except one host | Rotation does not update the template, and that host still holds the template's original secret | See [Rotate credentials](/pam/administration/accounts/rotation) | | A generated secret breaks an application login | A special character the application cannot handle | Add it to the excluded characters rather than dropping the class | ## Field reference — generation | Field | What it does | | ------------------- | ---------------------------------------------------------------------------------------------- | | Secret strategy | **Random generate** or **Specific secret** | | Secret type | Password, SSH Key, Token, Access Key, or API Key. Only passwords are composed from these rules | | Length | 4 to 100 characters | | Uppercase | Include uppercase letters | | Lowercase | Include lowercase letters | | Digits | Include digits | | Special characters | Include symbols | | Excluded characters | Characters the solution must never use in a generated secret | | Password | The value you type. Available only with **Specific secret** | Because the policy lives on each template and each task, different groups of assets can be given different complexity — a criticality tier or a platform family can have its own rules without changing anything global. ## Password rules for console users These are the rules applied to the **local users of the solution**, under **System settings › Security › Passwords**. They have no effect on the secrets generated for managed accounts. ### Basic | Field | Default | What it does | | ------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------- | | User password expiration (day) | `9999` | Days before a user's console password expires and must be replaced at the next sign-in. The default is effectively "never" | | Recent password count | `5` | How many previous passwords are remembered and refused when the user tries to reuse one | An expiry reminder is emailed to the user automatically, daily, for the five days before the password expires. ### Password rules | Field | Default | What it does | | ---------------------- | ------- | ------------------------------------------ | | Minimum length (User) | `6` | Minimum password length for ordinary users | | Minimum length (Admin) | `6` | Minimum password length for administrators | | Uppercase | — | Requires at least one uppercase letter | | Lowercase | — | Requires at least one lowercase letter | | Digits | — | Requires at least one digit | | Special characters | — | Requires at least one symbol | {% hint style="warning" %} The shipped defaults are permissive on purpose — a six-character password that never expires. For ISO 27001, SOC 2, PCI-DSS, or LGPD, DataDike's recommendation is a minimum of 12 characters for users and 16 for administrators, expiry at 90 days, and 5 to 10 remembered passwords. {% endhint %} To verify a change here, try to set a non-compliant password on a test user. It must be refused at the moment you save, not at the next sign-in. ## Related pages * [Rotate credentials](/pam/administration/accounts/rotation) — where the generation policy is used most * [Account templates](/pam/administration/accounts/account-templates) — the template's **Secret strategy** * [Managed accounts](/pam/administration/accounts/managed-accounts) — password history, and revealing a secret * [The credential vault](/pam/administration/accounts/vault) # Rotate credentials Rotate passwords and SSH keys automatically or on demand, and what to watch for when the credential is a domain account. ## What this is and when to use it A rotation task changes the secret of one or more accounts on one or more assets, stores the new value in the vault, and — for SSH keys — redistributes the new public key to the targets. Rotation runs on a schedule, on demand, or both. Use it to satisfy a rotation policy, and immediately after any event that may have exposed a credential. {% hint style="info" %} When a password changes, the solution also applies it to the **dependencies** registered for that credential — services, scheduled tasks, and applications that use the same account — so that rotation does not break integrations. Dependencies are declared in the account or task configuration and are updated in the same run. {% endhint %} ## Before you start * The asset registered under **Environment › Assets**. * The credential registered — discovered by an automation or added by hand, it makes no difference. * The credential linked to the host, either directly or through a template. * A management protocol reachable on the target: * **Windows** — WinRM or OpenSSH * **Linux** — SSH * Firewall open, both the network firewall and the host firewall. * For WinRM, the solution's IP added as a trusted host on the target. The solution must be able to reach **each** target to confirm the change. Hosts it cannot reach keep their old password. ## Steps 1. Open **Accounts › Automations › Change secret**. 2. Click **Create**. 3. Fill the fields — see the field reference below. The two that decide the blast radius are **Accounts** and **Assets or Nodes**. 4. Under **Password policy**, set the length and complexity of the generated secret. Match it to the strictest policy among the targets, not the loosest. 5. Under **Periodic**, set the schedule, or leave it off and run the task by hand. 6. Set **Recipient** if someone should be emailed the result. 7. Save, then run the task once manually before trusting the schedule. ## What you should see ![The Change secret screen, listing the rotation tasks](https://1085357737-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7xzJyi9JVzRwnV6JzUho%2Fuploads%2Fgit-blob-ef02a06c9d7871c068989567649927d011d8893c%2Frotation.png?alt=media) **1** How many rotation tasks exist. **2** One task, with the accounts and folders it covers. The task appears in the list with an execution counter. After a run, the execution log shows one line per asset, with success or failure per host. ## How to verify it worked Saving and even running the task is not proof. Verify the secret actually changed: 1. Open the account under **Accounts › Accounts**. 2. Open its **password history**. A new version must appear, dated at the run. 3. Open a session to the asset using that account. If the login succeeds, the vault and the target agree. Step three matters most. A run can report success and still leave a host behind — check the execution log host by host, not just the task status. ## Rotating a domain account Domain credentials behave differently from local ones, and this is where most mistakes happen. * The domain account must be registered as a **template**, and the template must be associated with the hosts that authenticate against it. That association is required for the credential to be usable at all, not only for rotation. * When you rotate, you specify both the **host where the change is executed** and the **hosts that must receive the new credential**. * The new password is visible under the account, but **the template keeps the original password**. The template is never updated by rotation; changing it is a manual action. * If you later associate the template with a **new host**, that host must be added to the rotation task. Otherwise it keeps the password stored in the template — which, for a domain account already rotated, no longer works. That last point is the usual cause of "it worked everywhere except on the new server". ## Rotating SSH keys The same task rotates SSH keys, scheduled or on demand. On each run the solution generates a new key pair, updates the key in the vault, and redistributes the public key to the associated target assets, so access continues without manual intervention. ## Common errors | Symptom | Cause | Fix | | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | `The password does not meet the password policy requirements` | The generated secret does not satisfy the target's own policy — length, complexity, or history | Raise the complexity in the task's **Password policy** to match the strictest target | | Some hosts succeeded, others failed | The solution could not reach those hosts | Check connectivity and the management protocol. Unreachable hosts keep the old password | | A new server still has the old domain password | It was added to the template but not to the rotation task | Add the host to the task and run it again | | The template shows an old password | Expected. Rotation never updates the template | Change the template by hand if you need it to match | | WinRM connection refused | Port 5985 blocked, or the solution's IP is not a trusted host | Open the port and add the IP to the WinRM trusted hosts | ## Field reference | Field | What it does | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | | Name | Identifies the task. Required | | Accounts | The logins whose password will change. Case-sensitive. Several accounts may be listed, but all receive the same generated secret in a given run | | Assets or Nodes | The target hosts, individually or by folder | | Password policy | The generation strategy and complexity of the new secret | | Automations › Parameters | Additional behavior, such as the groups the account belongs to. Use it so that no account is altered without your knowledge | | Periodic | The schedule. Manual execution remains available regardless | | Active | Enables or disables the task without deleting it | | Recipient | Email address notified with the run result | ## Related pages * [Managed accounts](/pam/administration/accounts/managed-accounts) * [Account templates](/pam/administration/accounts/account-templates) — why the template keeps its original secret * [Password generation policy](/pam/administration/accounts/password-policy) * [Collect accounts from an asset](/pam/administration/accounts/discovery-of-accounts) * [Detection and mitigation policy](/pam/administration/ueba/policy) — rotation triggered by a risk score # Collect accounts from an asset Collect the accounts that already exist on an asset, classify the privileged ones, and bring them under management. ## What this is and when to use it A collection task connects to an asset, lists the accounts that exist in its operating system, records their attributes, and classifies which of them hold administrative privilege. Run it when onboarding an environment, to find out what is actually there rather than what the inventory claims — and run it periodically afterwards, so that accounts created outside the solution do not stay invisible. ## Before you start * The host registered under **Environment › Assets** and reachable over SSH (Linux) or WinRM (Windows). * An administrative account on the host, active in the solution and with enough permission to list system accounts. * **Windows** — WinRM enabled and port 5985 open in the firewall. * **Linux** — Python 3 installed on the target, normally at `/usr/bin/python3`. {% hint style="warning" %} **The account the solution connects with.** By default the solution uses the `administrator` account of the asset to run the collection. If that account has reduced permission, has no password stored in the solution, or is disabled in the operating system, **disable it in the solution** — otherwise every run fails on it. Set it at **Environment › Assets › \ › Accounts › Administrator › Quick update › Active**. {% endhint %} ## Steps 1. Open **Accounts › Automations › Gather accounts**. 2. Click **Create**. 3. Fill the basic configuration — see the field reference below. 4. Decide whether to turn on **Sync with asset**. With it on, collected accounts are registered against the asset automatically. 5. Set **Periodic execution** if the collection should repeat. 6. Save and run once by hand. ## What you should see ![The Gather accounts screen](https://1085357737-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7xzJyi9JVzRwnV6JzUho%2Fuploads%2Fgit-blob-012e985d553b1296590ffc8e04a72163186498c2%2Faccount-collection.png?alt=media) **1** How many collection tasks exist. The run finishes and the task's **Executions** tab shows a log per host. The collected accounts appear against each asset, each with the date of the collection that found it. ## How to verify it worked 1. Open **Environment › Assets** and select one of the targets. 2. Open its **Accounts** tab. The accounts found in the operating system must be listed there, with the collection date. 3. Confirm that an account you know is privileged on that host carries the **privileged** marking. The classification is produced by the collection itself, not typed by an operator — if it is missing, the collection did not read the host's group membership. ## What is collected For every account found, the task records: | Group | What it collects | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Attributes** | Username, UID or identifier, shell, home directory, and group membership | | **Privilege** | `root` and accounts holding administrative privilege — members of `root`, `wheel`, or `sudo`, and accounts listed in sudoers on Linux; `Administrator` and members of administrative groups on Windows | | **Use** | Last login, which separates accounts actually in use from accounts that exist but sit idle — the basis for reviewing and disabling orphaned accounts | ## What collection reaches, and what it does not Automatic collection reads the account list from the operating system or the database engine. That is a narrower set than the assets the solution manages, and the difference matters when planning an onboarding. | Asset category | Accounts found automatically | How credentials get in otherwise | | ---------------------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | **Host** — Linux, Unix, Windows | Yes | — | | **Database** — MySQL, MariaDB, PostgreSQL, Oracle, MongoDB | Yes | — | | **Database** — SQL Server | No | Registered by hand, or imported in bulk | | **Device** — switches, routers, firewalls | No | Registered by hand, or imported in bulk | | **Web** — applications reached over HTTP or HTTPS | No | Registered by hand. The credential is then filled into the application's own login form | | **Cloud** | The *assets* are discovered from the provider. Their accounts are not | Registered by hand, or collected once the asset is a managed host | Two consequences worth planning around: * **A category with no automatic collection is not a category the solution cannot manage.** A web application's credential is held, rotated on a schedule you set, and used to sign in without the user seeing it, exactly like a host account. What is missing is only the step that finds the accounts for you. * **For everything not collected automatically, bulk import is the practical route.** Registering a few hundred network devices one screen at a time is how an onboarding stalls. For finding the *assets* themselves, including from cloud providers, see [Discover assets on the network](/pam/administration/assets/discovery). ## Common errors | Symptom | Cause | Fix | | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | `MODULE FAILURE` with empty `module_stdout` | The connection succeeded but the module could not start on the target. On Linux, Python missing or not at the expected path; on Windows, WinRM misconfigured or insufficient privilege | Install Python 3 on Linux; check WinRM authentication and privilege on Windows | | `Data could not be sent to remote host` / `Connection reset` | SSH not running, a firewall closing the connection after the handshake, an IDS or IPS dropping it, or the wrong user | Confirm the SSH service, the firewall, and the account used | | `The connection plugin 'rdp' was not found` | The host has no SSH protocol registered, so the task has no management channel | Add port 22 under **protocols** in the host's registration | | `ntlm: the specified credentials were rejected by the server` | NTLM incompatibility, not a wrong password | Check Windows event ID 4624 on the target — it shows the connection arrived and was blocked by NTLM negotiation | | Every host fails on the same account | The `administrator` account is disabled, unprivileged, or has no password stored | Disable that account in the solution, as described above | {% hint style="info" %} `rc: 0` in a `MODULE FAILURE` is misleading. It means the transport worked; the failure happened inside the target while starting the module. {% endhint %} ## Field reference | Field | What it does | | ------------------ | --------------------------------------------------------------------------------------------------------------- | | Name | Identifies the collection. Required | | Node | The folder of the environment where the operation runs | | Devices | The target assets | | Periodic execution | Shows the scheduling fields — **crontab** and **interval**, default 24 hours. If both are set, **crontab wins** | | Sync with asset | Registers the collected accounts against the assets automatically | | Active | Enables or disables the operation. On by default | | Custodian | The user responsible. Used only for email notification | | Comment | Free text | ## Related pages * [Managed accounts](/pam/administration/accounts/managed-accounts) * [Rotate credentials](/pam/administration/accounts/rotation) * [Discover assets on the network](/pam/administration/assets/discovery) — finding the hosts, before finding their accounts * [Asset inventory](/pam/administration/assets/inventory) # Access control | Page | What it covers | | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Authorizations](/pam/administration/access/authorizations) | The rule that grants a user access to an account on an asset, over which protocols, with which actions, and for how long. | | [Bulk authorizations](/pam/administration/access/bulk-authorizations) | Creating, updating, and exporting authorization rules in bulk with a CSV or XLSX file, and the account codes the file uses. | | [Just-in-time access](/pam/administration/access/just-in-time) | Access granted on demand for a limited period and revoked automatically, instead of a standing authorization that never expires. | | [Approval workflows](/pam/administration/access/approvals) | How a privileged action is held until someone releases it — the four rules that can require approval, who may decide, and where the decision is recorded. | | [Command inspection](/pam/administration/access/command-filtering) | Inspect commands before they run inside a session, and block, allow, queue for approval, or alarm on them. | | [Login policies](/pam/administration/access/login-policies) | Control when and from where users may sign in to the console, and what happens when they try outside those bounds. | # Authorizations The rule that grants a user access to an account on an asset, over which protocols, with which actions, and for how long. ## What this is and when to use it An authorization is the only thing that grants access. Without one, a user who can log in to the console still sees no assets and can open no sessions. Each rule joins three sides: | Side | What you choose | | -------- | ------------------------------------------------------------------------------- | | **Who** | Users, groups, or both | | **What** | Assets, folders, and which accounts on them | | **How** | Protocols, permitted actions, validity period, and whether approval is required | Create one whenever a person or team needs access to a set of assets. Prefer a few rules aimed at groups and folders over many rules aimed at individuals — they are far easier to audit. ## Before you start * The **SYSADMIN** profile. * The assets already registered, and the accounts you intend to grant. * The users or groups that will receive access. ## Steps 1. Open **Policies › Authorization**. The left pane is the asset folder tree; selecting a folder filters the rule list on the right to rules that touch it. 2. Click **Create**. 3. Give the rule a **name** that says who gets what — the name is what an auditor reads first. 4. Choose the subject under **Users** and **Groups**. Either may be left empty, but not both. 5. Choose the target under **Assets** and **Nodes**. Individual assets, whole folders, or a combination. 6. Choose which **accounts** the rule grants: * **All existing accounts** — every account on the asset * **Specified accounts** — a named list * **Virtual accounts** — the credential is not stored: * **Manual account** — the user types username and password at connection time * **Same account** — the solution uses the user's own PAM account name. If that account exists on the asset the login is automatic; otherwise the username is filled in and the user supplies the password * **Anonymous account** — no credential at all, for web and custom assets 7. Choose the **protocols**: all, or a specific list. 8. Choose the permitted **actions** — see the field reference below. 9. Set the **validity period**. Start and expiry are both timestamps. 10. Decide whether the access requires **approval**, and how many approvers. 11. Click **Submit**. ## What you should see ![The Authorization screen, listing the rules in force](https://1085357737-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7xzJyi9JVzRwnV6JzUho%2Fuploads%2Fgit-blob-66f5fc3a369edec446fb198fb5248e053f310c64%2Fauthorizations.png?alt=media) **1** How many rules exist. **2** One rule, with the subject it grants to. **3** Create, which opens the rule form. The new rule appears in the list on the right, with the **Valid** column showing whether it is currently in force. A rule can be saved and still be invalid — because it is inactive, or outside its validity period. ## How to verify it worked Do not trust the rule list. Verify from the user's side: 1. Sign in as one of the users the rule covers, or ask them to. 2. The granted assets must appear in their asset list. If they do not, the rule is not reaching that user. 3. Open a session to one of the assets, over one of the granted protocols. 4. Confirm the session appears under **Audit › Sessions**. If the assets appear but the session fails, the problem is usually the protocol list or the account selection, not the rule's subject. ## Common errors | Symptom | Cause | Fix | | -------------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------- | | The rule exists but grants nothing | Inactive, or outside the validity period | Check the **Valid** column, then the start and expiry dates | | The user sees no assets | The user is in neither the user list nor a granted group | Add the user or their group to the rule | | The asset appears but the session is refused | The protocol is not in the rule's protocol list | Add the protocol, or switch the rule to all protocols | | File transfer is blocked mid-session | The **Transfer** actions were not granted | Grant upload, download, or delete as needed | | A user has more access than expected | Two rules cover the same asset | When rules overlap, **the least restrictive one wins**. Find the other rule | | A session ends on its own | The authorization expired while the session was open | Active sessions are terminated automatically when the rule expires | ## Field reference ### Accounts | Option | What it does | | --------------------- | ---------------------------------------------------------- | | All existing accounts | Grants every account registered on the asset | | Specified accounts | Grants a named list | | Manual account | No stored credential; the user types username and password | | Same account | Uses the user's own PAM account name on the target | | Anonymous account | No credential; web and custom assets only | ### Protocols | Category | Protocols | | ------------- | --------------------------------------------------------- | | Remote access | SSH, SFTP, RDP, VNC, Telnet, WinRM | | Databases | MySQL, MariaDB, PostgreSQL, Oracle, SQLServer, DB2 | | Specialized | Redis, K8s, HTTP(S), ChatGPT, Dameng, ClickHouse, MongoDB | ### Actions | Action | What it permits | | ------------------- | --------------------------------------------------- | | Connect | Opening a session. Without it, nothing else applies | | Transfer › Upload | Sending files to the asset | | Transfer › Download | Retrieving files from the asset | | Transfer › Delete | Deleting files on the asset | | Clipboard › Copy | Copying from the session to the local clipboard | | Clipboard › Paste | Pasting from the local clipboard into the session | | Share | Sharing the live session with another user | | All | Every action above | ### Validity and approval | Field | What it does | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | Active | Turns the rule on or off without deleting it | | Date start / Date expired | The window in which the rule is in force. Sessions running when the rule expires are terminated | | Approval | Whether access requires approval before it is released, and how many approvers. Two or more approvers gives dual custody | ## Related pages * [Core concepts](/pam/get-started/core-concepts) — how authorizations relate to accounts, assets, and profiles * [Bulk authorizations](/pam/administration/access/bulk-authorizations) — building or updating many rules at once from a CSV or XLSX file * [Approval workflows](/pam/administration/access/approvals) * [Just-in-time access](/pam/administration/access/just-in-time) — access granted on demand instead of standing * [Command inspection](/pam/administration/access/command-filtering) — restricting what may be run inside a granted session # Bulk authorizations Creating, updating, and exporting authorization rules in bulk with a CSV or XLSX file, and the account codes the file uses. ## What this is and when to use it The authorization list can be driven from a file. You download a template, fill it in, and upload it; the console creates or updates one rule per row. The same screen exports the rules you already have. Reach for it when the work does not fit the form: | Situation | Why the file is better | | --------------------------- | --------------------------------------------------------------- | | First rollout | Hundreds of rules built from a spreadsheet you already maintain | | Moving between environments | Export from one, import into the next | | Reorganisation | Shifting many rules to new groups in one pass | | Expiry sweep | Pushing a new `Date expired` across a whole set | | Audit evidence | A dated file showing exactly who had access to what | For a handful of rules the form on [Authorizations](/pam/administration/access/authorizations) is faster and validates as you type. ## Before you start * The **SYSADMIN** profile. * The users, groups, and assets already registered. The file references them by internal id, so it cannot create them. * A spreadsheet tool that saves UTF-8. Accented names come back corrupted otherwise. {% hint style="warning" %} Export before you update. An update import overwrites the rules it names, and there is no undo inside the console. The exported file is the rollback. {% endhint %} ## Steps The controls sit at the top right of the authorization list: one icon imports, the other exports. ### Export for reading 1. Open **Console › Policies › Authorization**. 2. Optionally tick the rules you want. Leaving everything unticked exports the whole list. 3. Use the export icon. The **Export** dialog opens. 4. Choose **CSV** or **Excel**, then **Export all** or **Export only selected items**. 5. Confirm. The file downloads. {% hint style="danger" %} This file is for reading, not for round-tripping. It carries no ids, so it cannot be imported back. To change rules through a file, download the update template described below instead. {% endhint %} ### Create new rules 1. Use the import icon. The **Upload & Update** dialog opens. 2. Choose **Create**, then **Download created template**. 3. Fill the file in: * row 1 holds the column headers * row 2 holds filling instructions and can be deleted * row 3 onwards holds one authorization per row 4. Leave **ID** empty. The console assigns it. 5. Save, return to the dialog, choose **Create**, upload the file, and confirm. ### Update existing rules 1. Optionally tick the rules you want to change in the list first. 2. Use the import icon, choose **Update**, then **Download updated template**. 3. The file arrives already filled with the current values of those rules, or of every rule if you ticked none. 4. Change only the cells you mean to change, and **keep the ID column untouched**. The id is how the console recognises the rule; blank it and the row is treated as new. 5. Save, choose **Update**, upload, and confirm. ## What you should see A per-row result. Rows that validate are applied; rows that fail are reported with their reason and skipped, so a partial file still does useful work. Reload the list to see the rules that landed. ## How to verify it worked 1. Reload the authorization list and confirm the count moved by what you expected. 2. Open one imported rule in the form and check its users, accounts, protocols, and dates against the row you wrote. 3. Sign in as one of the granted users and confirm the asset is now visible. An imported rule with `Active` set to `No`, or a start date in the future, grants nothing yet, which looks identical to a failed import from the list alone. ## Common errors | What you see | Cause | Fix | | --------------------------------------- | ------------------------------- | ------------------------------------------------------------------------ | | Row rejected on the date | Wrong date shape | Use `2025/07/12 22:03:07 +0800`, including the offset | | Row rejected on a user, group, or asset | The id does not exist here | Ids are per environment. Re-export from *this* console to get valid ones | | Row rejected on a list field | Array syntax | Double quotes and JSON shape: `["ssh", "rdp"]`, and `[]` for empty | | Row rejected with no name | `Name` is required | Fill it; 128 characters maximum | | Accents come back as mojibake | The file was not saved as UTF-8 | Re-save as UTF-8 and upload again | | Upload refused outright | Over 10 MB, or not CSV/XLSX | Split the file | | An export will not import | It is the audit export | Download the update template instead | ## Field reference One row is one authorization. The names match the columns of the template. | Column | Shape | Notes | | ------------ | --------------------------- | ------------------------------------------------------------------- | | ID | internal id | Empty when creating. Required, and unchanged, when updating | | Name | text | Required, up to 128 characters | | Users | `["name(id)", ...]` | For example `["John(b8903cab-63a1-406b-8ba3-7eead1b5c592)"]` | | Groups | `["name(id)", ...]` | `[]` when none | | Assets | `["name(id)", ...]` | For example `["vmTestes(1c086d8a-1222-4c59-9402-0bde1d413b87)"]` | | Nodes | `["name(id)", ...]` | Asset-tree folders, same shape | | Tags | `[]` | Leave empty | | Accounts | `["name", "@CODE", ...]` | Real account names, the codes below, or both | | Protocols | `["all"]` or a list | For example `["ssh", "rdp", "vnc"]` | | Action | list | `connect`, `upload`, `download`, `copy`, `paste`, `delete`, `share` | | Active | `Yes` or `No` | | | Date start | `2025/07/12 22:03:07 +0800` | Offset included | | Date expired | same shape | | | Description | text | Free | ### Account codes The form offers the account options by name. The file uses a code for each, and the two are the same thing: | Code | Option on the form | What the session uses | | -------- | --------------------- | ----------------------------------------------------------- | | `@ALL` | All existing accounts | Every account registered on the asset | | `@SPEC` | Specified accounts | The named list you also put in the cell | | `@USER` | Same account | The account whose name matches the console user | | `@ANON` | Anonymous account | No credential. Web and custom assets only | | `@INPUT` | Manual account | The user types the username and password at connection time | Real names and codes mix in one cell: `["root", "admin", "@SPEC", "@USER"]`. ## Related pages * [Authorizations](/pam/administration/access/authorizations): the same rule built one at a time in the form, and what each field means. * [Users and groups](/pam/administration/identities/users-and-groups): the users and groups the file references. * [Folders and tags](/pam/administration/assets/folders-and-tags): the asset-tree folders that the `Nodes` column points at. # Just-in-time access Access granted on demand for a limited period and revoked automatically, instead of a standing authorization that never expires. ## What this is and when to use it Just-in-time (JIT) access replaces a standing grant with a request. Instead of holding permission to an asset permanently, the user asks for it when the work requires it; an approver decides; the grant is temporary and is **revoked automatically when it expires**. Sessions still open at that moment are terminated. Compare it with an [authorization](/pam/administration/access/authorizations), which is the standing form of the same thing: | | Authorization | Just-in-time request | | ----------------- | ------------------------------------------- | -------------------------------- | | Who initiates it | An administrator, in advance | The user, when the work needs it | | How long it lasts | Until the validity period ends, often years | A defined, short period | | How it ends | You edit or delete the rule | Automatically, at expiry | | Who decides | The administrator who wrote the rule | The designated approver | Use it for the accesses you do not want anyone holding by default: production databases, domain controllers, out-of-band consoles, and above all third parties. For a contractor, a determined term is the right shape of access — a permanent grant to a vendor account is the thing JIT exists to avoid. {% hint style="info" %} This page covers the concept and where JIT lives in the console. The request form varies by version: raise one request in a test tenant to see the form yours presents. {% endhint %} ## What a request narrows JIT cuts two dimensions at once, and the second is the one people forget. Reducing how long access lasts is worth little if, for that hour, the person holds everything they would have held permanently. A request names, and is granted for, only: | Dimension | What the request carries | | ------------------ | ------------------------------------------------------------------------------- | | **Which assets** | The individual assets, or the folders of the asset tree, being asked for | | **Which accounts** | The accounts on those assets that may be used, not every account they hold | | **Which actions** | Connect, and separately upload, download, copy, paste, delete, share | | **For how long** | A start and an expiry. Access appears at the first and is revoked at the second | So a grant can be "read-only access to one account on two hosts, this afternoon" rather than "administrator, today". The approver sees each of those dimensions before deciding, which is what makes the approval a real decision instead of a rubber stamp. {% hint style="warning" %} Ask for the actions you need, not the full set. A request that includes **upload** and **download** because the form offered them is a request for file transfer into production, and it will be read that way in an audit. The narrower request is also the one an approver grants faster. {% endhint %} ## Where it lives in the console ![The Just in time screen](https://1085357737-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7xzJyi9JVzRwnV6JzUho%2Fuploads%2Fgit-blob-e3925ff3fc4176c89a008176a540f843dd07a946%2Fjust-in-time.png?alt=media) JIT is spread across three screens, in two different areas: | Screen | Area | What it is for | | --------------------------- | -------- | --------------------------------------------------------- | | **Policies › Just in Time** | Sysadmin | The administrator's view of just-in-time access | | **My requests** | Cockpit | Where a user raises a request and follows its status | | **To approve** | Cockpit | Where an approver finds pending requests and decides them | The requester and the approver each have their own dedicated area, so an approver does not need administrator rights to decide a request — only the profile that grants them the approver role. ## How a request flows 1. The user signs in, with MFA where it is required. 2. From **My requests**, the user requests access to a specific asset. 3. The approver is notified, finds the request under **To approve**, and approves or rejects it. The decision is recorded. 4. On approval the access is granted for the requested period. The asset appears in the user's own access list and the credential is supplied by the solution, as with any other granted access. 5. At expiry the grant is revoked automatically, and any session still running on it is terminated. {% hint style="danger" %} **You cannot approve your own request** — being an administrator does not change this. If the only approver on a rule is also the only person who needs the access, nobody can release it. {% endhint %} ## How to verify it worked Like any approval flow, this needs two accounts — a requester and an approver. 1. As the requester, raise a request from **My requests**. It must appear there with a pending status. 2. As the approver, from a different account, confirm it is listed under **To approve**, and approve it. 3. Back as the requester, the asset must now appear in the access list, and a session to it must open. 4. Wait for the grant to expire, or revoke it. The asset must disappear from the requester's list, and a session left open must be dropped. Step 4 is the one worth doing at least once. The whole value of JIT is the automatic revocation, and it is the only part of the flow that fails silently — an access that quietly never expires looks exactly like one that works. ## Common errors | Symptom | Cause | Fix | | ------------------------------------------------------ | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | The approver never sees the request | No notification transport, or the wrong person is designated as approver | Configure email or SMS under **System settings › Notifications**, then check who the rule names as approver | | The only approver cannot approve | The approver is also the requester, and self-approval is not permitted | Designate a second approver | | Approved, but the user still sees no asset | The grant has already expired, or the request covered a different asset or account | Check the request's period and its target | | A session ended without warning | The grant expired while the session was open | Expected. Revocation terminates running sessions | | Nobody uses it, and standing access is granted instead | Requesting is slower than asking an administrator | Approvals must be answered quickly, or the workflow is bypassed in practice | ## Related pages * [Approval workflows](/pam/administration/access/approvals) — everything else that can be held for approval * [Authorizations](/pam/administration/access/authorizations) — the standing grant JIT is an alternative to * [Reports](/pam/administration/audit/reports) — the approvals and access-requests report * [Users and groups](/pam/administration/identities/users-and-groups) — external and third-party users # Approval workflows How a privileged action is held until someone releases it — the four rules that can require approval, who may decide, and where the decision is recorded. ## What this is and when to use it An approval workflow holds a privileged action until a designated person releases it. The requester waits, the approver is notified, and the decision is recorded for auditing. There is no single "approvals" screen. **Approval is a setting on the rule that governs the action**, so where you turn it on depends on what you want held: | What is held | Where you turn it on | | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | | Access to an account on an asset | The **approval** setting on an [authorization](/pam/administration/access/authorizations), per account or account group | | Sign-in to the console | A user login rule with the **Review** action — see [Login policies](/pam/administration/access/login-policies) | | A connection to a specific asset | An asset connect rule with the **Review** action, under **Policies › Asset connect** | | A command typed in a session | A command filter with the **Review** action — see [Command inspection](/pam/administration/access/command-filtering) | | Access the user does not have at all | A request raised by the user — see [Just-in-time access](/pam/administration/access/just-in-time) | Use approval where a standing grant is too much but a hard block is too little: production databases, domain controllers, out-of-band consoles, third-party accounts. {% hint style="danger" %} **You cannot approve your own access.** Even if your profile is administrator and you are listed as an approver on the rule, the solution will not let you release a request you raised. Always designate at least one other approver, or the access is unusable in practice. {% endhint %} ## Before you start * The **SYSADMIN** profile to configure the rule. * At least one approver who is **not** the person who will be requesting. * Email or SMS notification configured under **System settings › Notifications**. Approval requests are announced to the credential owners by email or SMS; with no transport configured, requests sit unnoticed. ## Where approval is configured ### Access to an account On an authorization, each **account** or **account group** is granted in one of two ways: * **Without approval** — access is released directly to the authorized user. * **With approval** — access requires one or more approvers before it is released. The **number of approvers** and who they are is configurable per account or account group. Two or more approvers gives you dual custody: no single person can release the credential. ### Console sign-in A user login rule set to **Review** holds the sign-in itself. The user is told that approval is required and waits; the approver is notified and may approve, reject, or ask for more information; the decision is recorded. ### A connection to an asset An asset connect rule set to **Review** holds a specific connection rather than the sign-in. Configure it under **Policies › Asset connect**, scoping the rule by users, assets, accounts, and time, and setting **Action** to **Review**. Like all rules of this kind it carries a **Priority** from 1 to 100, default 50, and **the lower number is evaluated first**. A permissive rule with a smaller number will match before your Review rule and the approval will never be asked for. ### A command in a session A command filter set to **Review** queues the command for approval instead of running or rejecting it. The session waits while the approver decides. ## Steps 1. Decide which action you want held — access to a credential, a sign-in, a connection, or a command. That decides which rule you edit. 2. Open the rule and set approval: * on an authorization, switch the account or account group to require approval and set the number of approvers * on a login, asset connect, or command filter rule, set **Action** to **Review** 3. Name the approvers. Include someone other than the expected requesters. 4. On login, asset connect, and command filter rules, check the **Priority** against the other rules that could match the same attempt. 5. Save, and confirm the rule is **Active**. ## What you should see Nothing changes on the rule list beyond the action or approval setting. The workflow becomes visible only when someone triggers it: the requester's action is held with a message saying approval is required, and the pending item appears for the approver — under **Cockpit › To approve** for access requests. ## How to verify it worked Approval is one of the few features you cannot verify from a single account. You need two: a requester and an approver. 1. As a user covered by the rule, trigger the action — open the asset, sign in, or type the command. 2. The action must be **held**, not allowed and not refused. If it goes through, the rule did not match; check its scope and its priority. 3. As the approver, from a **different** account, find the pending request and decide it. 4. Confirm the outcome matches the decision: approved lets the action proceed, rejected leaves it blocked. 5. Open **Audit › Sessions › Requests** and confirm the request and its decision are both recorded. The **Approvals / access requests** report gives the same data over a period — see [Reports](/pam/administration/audit/reports). Step 5 is the part that matters for compliance. A workflow that releases access but records nothing is worse than no workflow, because it looks like a control. ## Common errors | Symptom | Cause | Fix | | ---------------------------------------------------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | The approver is never notified | No email or SMS transport configured | Configure notifications under **System settings › Notifications** | | Nothing is held — the action just succeeds | The rule did not match, or a permissive rule with a lower priority number matched first | Check the rule's user, asset, and account scope, then compare priorities across all rules that could match | | I am an approver but cannot release my own request | Self-approval is not permitted, administrator or not | Have another approver decide | | Access reaches more people than the approval rule expected | Two authorizations cover the same asset, and **the least restrictive one wins** | Find the other authorization — see [Authorizations](/pam/administration/access/authorizations) | | Access was approved, then the session ended by itself | The authorization's validity period expired while the session was open | Sessions are terminated automatically at expiry. Extend the period or raise a new request | | A request was approved but the user still sees nothing | The grant was temporary and has already expired | Check the request's validity, not the authorization | ## Field reference | Setting | Where | What it does | | ------------------- | --------------------------------------------------- | ------------------------------------------------------------------ | | Approval required | Authorization, per account or account group | Holds access until an approver releases it | | Number of approvers | Authorization, per account or account group | 1 for simple approval, 2 or more for dual custody | | Action = Review | User login, asset connect, and command filter rules | Holds the sign-in, the connection, or the command pending approval | | Priority | User login, asset connect, and command filter rules | 1 to 100, default 50. Lower is evaluated first | | Active | All rules | Whether the rule is in force | ## Related pages * [Authorizations](/pam/administration/access/authorizations) — where access approval and the number of approvers are set * [Just-in-time access](/pam/administration/access/just-in-time) — requesting access you do not have * [Login policies](/pam/administration/access/login-policies) — the **Review** action on sign-in * [Command inspection](/pam/administration/access/command-filtering) — the **Review** action on a command * [Reports](/pam/administration/audit/reports) — the approvals and access-requests report # Command inspection Inspect commands before they run inside a session, and block, allow, queue for approval, or alarm on them. ## What this is and when to use it Command inspection sits between the user and the target. Every command typed in a session is intercepted **before execution**, compared against the rules that apply to that user, asset, and account, and then allowed, blocked, queued for approval, or allowed with an alert. It is the control that turns "this person has shell access" into "this person has shell access, minus the things nobody should do on this host". Use it on production assets, on shared administrative accounts, and wherever a single mistyped command is expensive. {% hint style="info" %} Inspection is enforced on the server, not in the client. It also applies to commands run through **adhoc** automations, not only to interactive sessions, and every attempt is written to the audit trail whether it ran or not. {% endhint %} ## How it works Two objects, and they are easy to confuse: | Object | What it is | | ------------------ | ------------------------------------------------------------------------------------------------------------------- | | **Command group** | A catalog of commands or patterns — *what* to look for | | **Command filter** | A rule that applies groups to a set of users, assets, and accounts, with an action — *who, where, and what happens* | A group on its own does nothing. A filter is what puts it into force. The sequence on every command: 1. The user types a command during a session 2. The solution intercepts it before execution 3. It looks for a filter matching that user, asset, and account combination 4. It compares the command against the groups attached to that filter 5. It applies the filter's action 6. It records the attempt for auditing ## The four actions | Action | What happens | When to use it | | ---------- | -------------------------------------------------------------------------------- | ---------------------------------------------------- | | **Reject** | Blocked immediately and never reaches the target. The user is told it was denied | Commands nobody should run on that host | | **Accept** | Allowed and executed normally | Carving exceptions out of a broader restrictive rule | | **Review** | Held in an approval queue. A designated approver is notified and decides | Critical but legitimate commands | | **Alarm** | Executed normally, but raises an alert to administrators | Watching suspicious activity without stopping work | ## Steps ### 1. Create the command group 1. Open **Policies › Command inspection**, and go to the **Command group** tab. 2. Click **Create**. 3. Give it a **Name** that says what it catches — *Destructive commands*, *Network changes*. 4. Choose the **Type**: * **Command** — literal commands * **Regular expression** — a pattern, for families of commands 5. Fill **Content**, one command per line: ```bash rm reboot hostname sudo df -h ``` 6. Decide whether to **ignore case**. 7. Save. {% hint style="warning" %} With **Type = Command**, matching is literal, **spaces included**. `sudo df -h` and `sudo df -h` are different strings and the second will not match. When spacing or arguments vary, use a regular expression instead. {% endhint %} ### 2. Create the filter 1. Go to the **Command filter** tab and click **Create**. 2. Set the **Name** and the **Priority** — numeric, lower is processed first, default 50. 3. Choose the **User** scope: all users, specific users, or filtered by attribute. 4. Choose the **Asset** scope the same way. 5. Attach the command groups and choose the **action**. 6. Save. ## What you should see ![The Command filter ACL tab, listing the filters](https://1085357737-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7xzJyi9JVzRwnV6JzUho%2Fuploads%2Fgit-blob-cf94d2bf9b80b376b8ec05369df2a52f5609f139%2Fcommand-inspection.png?alt=media) **1** How many filters exist. **2** One filter, with its priority. The Command group tab holds the catalogs the filters apply. The filter appears in the list with its priority. Priority matters as soon as two filters can apply to the same session — the lower number is processed first. ## How to verify it worked The rule list proves nothing. Test it from a session: 1. Open a session to a covered asset, as a covered user, using a covered account. 2. Type one of the commands in the group. 3. The expected outcome depends on the action: * **Reject** — the command does not run and the user is told it was denied * **Review** — the session waits, and the approver is notified * **Alarm** — the command runs, and an alert is raised 4. Open the audit trail and confirm the attempt was recorded, including when it was blocked. If nothing happens, the usual cause is that the filter's user, asset, or account scope does not actually cover the session you just opened. ## Common errors | Symptom | Cause | Fix | | ------------------------------------------ | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | The command runs although it is in a group | The group is not attached to any filter, or the filter's scope misses this session | Check that a filter attaches the group and that its user, asset, and account scope covers the session | | A command matches sometimes and not others | Literal matching, and the spacing or arguments vary | Switch the group to a regular expression | | A blocked command should have been allowed | A broader filter has higher priority | Lower the number on the more specific filter | | Nothing is blocked for one user | Another filter with **Accept** and a lower number matches first | Review priorities across filters, not one at a time | ## Field reference ### Command group | Field | What it does | | ----------- | ------------------------------------------------------------------------- | | Name | Identifies the group | | Type | **Command** for literal strings, **Regular expression** for patterns | | Content | One command or pattern per line. Literal matching respects spaces exactly | | Ignore case | Makes matching case-insensitive | ### Command filter | Field | What it does | | -------- | ----------------------------------------------------- | | Name | Identifies the rule | | Priority | Numeric. Lower is processed first. Default 50 | | User | All users, specific users, or filtered by attribute | | Asset | All assets, specific assets, or filtered by attribute | | Action | Reject, Accept, Review, or Alarm | ## Ready-made command catalogs DataDike publishes maintained lists of commands worth blocking, by platform, at [DataDike-commands-block](https://github.com/DataDike/DataDike-commands-block) — with folders for AIX, Cisco, Fortinet, Linux, Oracle, and Windows. They are a starting point, not a policy. Read them before applying them. ## Related pages * [Authorizations](/pam/administration/access/authorizations) — granting the session that inspection then restricts * [Approval workflows](/pam/administration/access/approvals) — where **Review** sends the command * [Audit trail](/pam/administration/audit/audit-trail) — where every attempt is recorded # Login policies Control when and from where users may sign in to the console, and what happens when they try outside those bounds. ## What this is and when to use it A login rule controls **when** and **from where** a user may sign in to the solution — not what they may reach afterwards, which is what [authorizations](/pam/administration/access/authorizations) decide. Use it to confine console access to working hours, to corporate networks, or to require a supervisor's approval for out-of-hours sign-in. Typical uses: * Access only during business hours, blocked outside them * Access only from corporate address ranges * Supervisor approval for sign-in to a critical environment * A compliance record of every attempt, allowed or refused ## Before you start * The **SYSADMIN** profile. * The address ranges you consider corporate, in CIDR. * For **Review**, someone designated to approve. ## Steps 1. Open **Policies › User login**. 2. Click **Create**. 3. Set the **Name** and the **Priority** — 1 to 100, default 50. 4. Choose the **target users**: all users, a specific list, or **Filter by attribute**, where you add one or more *attribute · match · value* lines to catch a department or a role. 5. Set the **IP** restriction. See the accepted formats below. 6. Define the **allowed periods** on the time grid. The grid has two columns, `00:00–12:00` and `12:00–24:00`, and one row per weekday. Click and drag to select. 7. Choose the **action**: Accept, Reject, Review, or Notify. 8. Tick **Active** for the rule to take effect. 9. Save. {% hint style="danger" %} **An empty grid does not block everything — it allows everything.** If no interval is selected, the rule applies 24/7. To block a day, that day must have no selection *while other days do*. {% endhint %} ## What you should see ![The User login screen, listing the login rules](https://1085357737-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7xzJyi9JVzRwnV6JzUho%2Fuploads%2Fgit-blob-890f6646f0cad5ee2d00571fa37cbf03bee7a9cd%2Flogin-policies.png?alt=media) **1** How many rules exist. **2** One rule, with its priority and active state. The rule appears in the list with its priority and active state. Nothing about the list tells you it is working. ## How to verify it worked 1. Ask a covered user to sign in from a covered address, inside the allowed window. It must succeed. 2. Repeat outside the window, or from an address outside the range. The outcome must match the action: * **Reject** — sign-in refused * **Review** — sign-in held, and the approver notified * **Notify** — sign-in succeeds and administrators are notified 3. Open the audit trail and confirm both attempts were recorded. Test the refusal, not only the success. A rule that never refuses anything is indistinguishable from no rule at all, and that is the failure mode that goes unnoticed for months. ## The four actions | Action | What happens | | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Accept** | Sign-in is authorized automatically | | **Reject** | Sign-in is blocked | | **Review** | Sign-in is held pending approval. The user is told approval is required and waits; the approver is notified and may approve or refuse; the decision is recorded for auditing | | **Notify** | Sign-in proceeds, and the designated administrators are notified | ## Priority Rules are evaluated in priority order, and **the lower the number, the higher the priority**. Put restrictive rules low and permissive rules high — 1 to 30 for the security rules that must always be evaluated first, 70 to 100 for the general ones. Getting this backwards is the usual reason a blocking rule appears to do nothing: a permissive rule with a smaller number matched first. ## Field reference | Field | What it does | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | Name | Identifies the rule | | Priority | 1 to 100, default 50. Lower is evaluated first | | Users | All users, a specific list, or filtered by attribute | | Filter by attribute | Lines of *attribute · match · value*, combinable, to target a department or role | | IP | Origin restriction. Accepts a single address `192.168.1.10`, a range `192.168.1.0/24`, a list `192.168.1.10, 192.168.1.20`, or IPv6 `2001:db8::1/64` | | Time grid | Allowed periods, per weekday. **Empty means 24/7** | | Action | Accept, Reject, Review, or Notify | | Active | Whether the rule is in force | ## Related pages * [Authorizations](/pam/administration/access/authorizations) — what a signed-in user may reach * [Approval workflows](/pam/administration/access/approvals) * [Multi-factor authentication](/pam/administration/identities/mfa) * [Audit trail](/pam/administration/audit/audit-trail) # Sessions | Page | What it covers | | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Connection methods](/pam/administration/sessions/connection-methods) | Control which protocols and clients a user may use to reach an asset — not which assets they may reach. | | [SSH sessions](/pam/administration/sessions/ssh) | How a user reaches a Linux, Unix, or network-device asset over SSH — from the browser or from their own client on port 2222 — and the connection string, authentication order, and global switches that decide whether it works. | | [RDP sessions](/pam/administration/sessions/rdp) | Graphical access to Windows assets, in the browser or through the local RDP client, and the platform variant, port, and display settings that decide whether the connection negotiates at all. | | [Web sessions](/pam/administration/sessions/web) | Register a web application as an asset so the solution opens it in a browser and types the credential for the user, with the session recorded. | | [Database sessions](/pam/administration/sessions/database) | Brokered access to eleven database platforms, through the web console or a native client, with query recording and command control. | | [File transfer](/pam/administration/sessions/file-transfer) | The four ways files move between a user's workstation and a protected asset — in-browser explorer, bulk upload, an external SFTP client, and the CLI — and what each one records. | | [Session recording](/pam/administration/sessions/recording) | Configure what is captured during a session and where it is kept — the object storage backend for replays, the separate store for commands, watermarking, and how retention of metadata differs from retention of files. | | [Live monitoring and termination](/pam/administration/sessions/live-monitoring) | Watch, pause, resume, or cut off a privileged session while it is still running, disconnect a console login, and let users share a live terminal with a colleague. | # Connection methods Control which protocols and clients a user may use to reach an asset — not which assets they may reach. ## What this is and when to use it A connect method rule controls **how** a user connects to an asset. It is easy to confuse with [authorizations](/pam/administration/access/authorizations), so it is worth stating plainly: | Policy | Answers | | -------------- | ------------------------------------------------------- | | Authorization | *Which* assets and accounts a user may reach | | Connect method | *How* they may reach them — which protocols and clients | Controlling access without controlling the method leaves the weakest available path open. Use these rules to remove connection methods that are unsuitable for a given audience: denying a native client to third parties so that everything goes through the recorded web session, for example, or removing a protocol that your security policy does not allow for privileged access. {% hint style="warning" %} The only available action is **Reject**. A rule denies the selected methods to the users it matches; there is no rule that grants a method. Everything not denied remains available. {% endhint %} ## Before you start * The **SYSADMIN** profile. * A clear idea of which method should remain, not only which one to remove. Denying every method for a user denies their access entirely. ## Steps 1. Open **Policies › Connect method**. 2. Click **Create**. 3. Under **Basic**, set the **Name** and the **Priority** — numeric, default 50, and **lower is evaluated first**. 4. Choose the users. With **Filter by attribute**, click **Add** and build each line as *Attribute name · Match · Attribute value*. See the operators below. 5. Under **Connect method**, select the methods the rule covers. Several may be selected. 6. Under **Action**, **Reject** is selected and is the only option. 7. Tick **Active**, and write a **Description** saying why the rule exists — the reasoning is what the next administrator will need. 8. **Submit**, or **Save & Continue** to keep editing. {% hint style="info" %} Leave gaps between priority numbers — 10, 20, 30 rather than 1, 2, 3 — so a new rule can be inserted between two existing ones later without renumbering everything. {% endhint %} ## What you should see ![The Connect Method ACL screen](https://1085357737-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7xzJyi9JVzRwnV6JzUho%2Fuploads%2Fgit-blob-474394bfaef293a487e999464777f8841d56a6d4%2Fconnection-methods.png?alt=media) **1** How many rules exist. **2** One rule. Reject is the only action a rule can take. The rule appears in the list, ordered by priority, with its active state and description. ## How to verify it worked 1. Sign in as one of the users the rule matches. 2. Open the connection dialog for a granted asset. 3. The denied methods must not be offered. If they are still there, the rule's user scope does not cover this user, or a rule with a lower number matched first. 4. Confirm that a method you intended to keep is still available. This is the check people skip, and it is how a rule quietly removes all access. ## Attribute filters When several filter lines are added they combine with **AND** — every line must match. | Operator | Meaning | Example | | ------------------ | ---------------------- | ------------------------------------- | | Equals | Exact match | Name = `João Silva` | | Not equal to | Anything but the value | Department ≠ `IT` | | In… | The value is in a list | Role in `[Admin, Manager]` | | Contains | Contains the substring | Name contains `Silva` | | Starts with… | Begins with the text | Email starts with `admin` | | Ending with… | Ends with the text | Email ends with `@company.com` | | Regular expression | A regex pattern | Email matches `^[a-z]+@company\.com$` | Some operators are case-sensitive. Test a regular expression before putting it into production — a pattern that matches nothing produces a rule that silently does nothing. ## Field reference | Field | What it does | | --------------- | ------------------------------------------------------- | | Name | Identifies the rule | | Priority | Numeric, default 50. Lower is evaluated first | | Users | All users, a specific list, or filtered by attribute | | Connect methods | The methods the rule covers. Multiple selection | | Action | **Reject**, and only Reject | | Active | Whether the rule is in force. Changes apply immediately | | Description | Free text. Record the security rationale here | {% hint style="danger" %} Deleting a rule is irreversible. Deactivate it first and confirm nothing breaks before removing it. {% endhint %} ## Related pages * [Authorizations](/pam/administration/access/authorizations) — which assets, rather than how * [SSH sessions](/pam/administration/sessions/ssh) * [RDP sessions](/pam/administration/sessions/rdp) * [Session recording](/pam/administration/sessions/recording) # SSH sessions How a user reaches a Linux, Unix, or network-device asset over SSH — from the browser or from their own client on port 2222 — and the connection string, authentication order, and global switches that ## What this is and when to use it For SSH the solution behaves as a **bastion host**. The user connects to the solution, not to the asset: the solution authenticates them, checks the authorization, opens the connection to the target with the stored credential, and records everything that follows. The user never needs the asset's password. There are two ways in, and both produce the same recorded session: | Method | Where it runs | Typical use | | ----------------- | ------------------------------------------------------ | -------------------------------------------------------------------------- | | **Web CLI** | A terminal in the browser | Day-to-day access, third parties, anyone without a client installed | | **Native client** | PuTTY, MobaXterm, Termius, OpenSSH, VS Code Remote-SSH | Engineers who want their own tooling, key-based access, an SFTP side panel | {% hint style="warning" %} Two ports are involved and confusing them is the most common mistake here. Port **22** is the asset's own SSH port, used by the solution to reach the target. Port **2222** is the solution's own SSH listener — that is what a native client connects to. The default is 2222 rather than 22 so that it does not collide with the sshd of the host the solution runs on. {% endhint %} Native-client access can be switched off for the whole platform, which forces every SSH session through the recorded browser terminal. See **Client connection** in the field reference. ## Before you start * The asset registered with the **SSH** protocol on a reachable port, running OpenSSH — on Windows too, if you intend to reach a Windows host over SSH. * An account on the asset, registered in the solution. * An authorization granting the user that asset, that account, the **SSH** protocol, and the **Connect** action. See [Authorizations](/pam/administration/access/authorizations). * Port **2222** open from the user's workstation to the solution's address, if they will use their own client. * No [connect method](/pam/administration/sessions/connection-methods) rule denying the client they intend to use. ## Connecting from the browser 1. Open the device access list, right-click the asset, and choose to connect. 2. Select the **SSH** protocol in the left-hand menu of the **Connect** dialog. 3. Choose the account under **Select account**. 4. Set the connection method to **Web**, and click **Connect**. ## Connecting from a native client Every client is configured the same way: the host is the **solution's** address, the port is **2222**, and the username carries the routing information. Two string formats exist: ``` # Interactive: lands in a menu listing the assets you are authorized for ssh -p 2222 @ # Direct: goes straight to one asset and account, no menu ssh -p 2222 @@@ ``` | Parameter | Meaning | Example | | -------------- | ------------------------------- | --------------- | | `pamUser` | Your username in the solution | `joao.silva` | | `assetAccount` | The account on the target asset | `root` | | `assetAddress` | The asset's address | `192.168.1.100` | | `pamAddress` | The solution's address | `10.0.0.50` | | `-p 2222` | The solution's SSH port | `2222` | The console can generate the string for you, in two further forms that identify the asset by its UUID rather than by its address: ``` # Permanent credential ssh ##@ -p 2222 # One-off connection token ssh @ -p 2222 ``` {% hint style="warning" %} A connection token is short-lived and comes with a one-time password of its own. Do not save a token in `~/.ssh/config` — the entry will look correct and stop working the moment the token expires. Keep permanent entries for the credential form and the manual form only. {% endhint %} ### Putting the string into `~/.ssh/config` Clients that ask for host, port, and user separately — including the VS Code **Remote-SSH** extension — need the string broken up. The rule is the same whichever format you started from: * everything **before the last `@`** goes in `User` * the address **after the last `@`** goes in `HostName` * the number after `-p` goes in `Port` ``` Host pam-prod-web HostName 10.0.0.50 User joao.silva@root@192.168.1.100 Port 2222 ``` Then connect with `ssh pam-prod-web`. ### Authentication order The client prompts in sequence, and what it asks for is not what the prompt names suggest: 1. **Password** — your password *in the solution*, never the asset's password. 2. **OTP code** — the six-digit code from your authenticator app, requested only when MFA is enabled on your account. In a plain terminal this arrives as an `[MFA verify]` prompt. To authenticate with a key instead, generate a pair, register the public half under **Personal settings › SSH keys**, and connect with `-i`: ``` ssh-keygen -t rsa -b 4096 -f ~/.ssh/datadike_key ssh -p 2222 -i ~/.ssh/datadike_key joao.silva@10.0.0.50 ``` The solution can also generate the pair for you. In that case the private key is downloadable **once**, immediately after creation; miss that download and the only remedy is to create another key. ## What you should see The interactive form opens a menu of the assets you are authorized for, and picking one drops you into a shell on the target. The direct form skips the menu. Either way you are on the asset as the account you chose, and `whoami` and `hostname` should confirm it — if they report the solution's own host, the routing part of the username was wrong and you never left the bastion. ## How to verify it worked 1. Type something identifiable in the session, then disconnect. 2. Open **Audit › Sessions** and confirm a record exists with protocol **SSH**, the account you used, and your workstation as the source address. 3. Open the session's **Commands** tab, or **Audit › Commands**, and confirm the command you typed is listed. This is the check that proves the session was really brokered — a connection that reached the asset directly leaves no command record. 4. Confirm **Replay** is offered on the finished session. See [Session recordings](/pam/administration/audit/recordings). If what you changed was native-client access, verify from the user's side instead: the **Connect** dialog must no longer offer the client method for any asset. ## Common errors | Symptom | Cause | Fix | | -------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | Connection refused, or times out on 2222 | The solution's SSH listener is unreachable | Test `telnet 2222`; check the firewall along the path and that the platform's services are running | | Credentials rejected | The asset's password was typed instead of the solution's | Use your password in the solution; the asset credential is injected for you | | Credentials rejected with the right password | No authorization covers this user, asset, and account | Check the rule — asset, account, and the SSH protocol all have to be in it | | `Permission denied (publickey)` | The private key file is readable by others, or the key is not registered | `chmod 400 key.pem` on Linux and macOS; `icacls "key.pem" /inheritance:r /grant:r "%username%:R"` on Windows | | The client rejects the connection string | The `@` segments are in the wrong order, or one is missing | Rebuild it as *pamUser\@assetAccount\@assetAddress\@pamAddress* and check that the last `@` precedes the solution's address | | A user removed from AD still gets in | Their SSH public key is still registered and public-key authentication is enabled | Disable **Public key** when identities come from AD or LDAP — see the warning below | | The session drops while idle | The idle timeout closed it | Raise **Max idle time** in **System settings › Security › Sessions**, or accept the behaviour | | "Session in use" when connecting | Another session already holds the asset | Wait, or have an administrator end the earlier one from **Audit › Sessions › Online** | {% hint style="danger" %} If users are authenticated through AD or LDAP, turn **Public key** off. A user removed from the directory whose public key is still registered in the solution can keep opening SSH sessions, walking straight past your offboarding process. Password authentication follows the directory; a registered key does not. {% endhint %} ## Field reference Global terminal settings, at **System settings › Components › Basic** under **SSH & Terminal protocol**. They apply to every SSH, Telnet, and SFTP session on the platform: | Field | Default | What it does | | ----------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Client connection | Enabled | Allows connections from native SSH clients. Disabling it removes the client option from the **Connect** dialog and forces every session into the browser terminal | | Password | Enabled | Allows password authentication against the terminal connector. The asset's own credential is injected by the solution either way and is never shown to the user | | Public key | Enabled | Allows SSH public-key authentication. Turn it off when identities come from AD or LDAP | | Asset sorting | Name | Order of the asset list offered at connection time: **Name** alphabetically, or **Address** by IP or hostname | | Asset page size | Auto | Assets per page in that list. **Auto** sizes it to the user's window; set a number for very large inventories | Session limits, at **System settings › Security › Sessions**: | Field | Default | What it does | | ---------------------- | ------- | ---------------------------------------------------------- | | Max idle time (minute) | 30 | Disconnects a session idle for longer than this | | Max online time (hour) | — | Disconnects a session open longer than this, active or not | The port the solution listens on for SSH belongs to the TCP port policy and defaults to **2222**. ## Related pages * [Connection methods](/pam/administration/sessions/connection-methods) — removing the native client for a given audience * [File transfer](/pam/administration/sessions/file-transfer) — SFTP over the same account and port * [Command filtering](/pam/administration/access/command-filtering) — blocking commands inside the session * [Session recording](/pam/administration/sessions/recording) — what an SSH session leaves behind * [Ports and protocols](/pam/reference/ports) — the port used to reach each platform # RDP sessions Graphical access to Windows assets, in the browser or through the local RDP client, and the platform variant, port, and display settings that decide whether the connection negotiates at all. ## What this is and when to use it An RDP session gives a user a Windows desktop through the solution. The graphical connector sits in the middle: it establishes the RDP connection with the stored credential, streams the screen to the user, and records the session as video. VNC works the same way, through the same connector. There are two ways in: | Method | Where it runs | Notes | | ----------------- | ------------------------------------- | ----------------------------------------------------------------------------------- | | **Web GUI** | A remote desktop in the browser | Nothing to install on the user's machine. This is the path third parties should use | | **Native client** | The local RDP client, such as `mstsc` | Connects to the solution's RDP listener, not to the asset | If the user only needs one application rather than a whole desktop, publish it instead of the desktop: **RemoteApp** and **VirtualApp** run a single executable — a browser, a database client, an IDE — on a publishing host, with the session brokered and recorded in the same way. That avoids handing out a full interactive desktop for the sake of one tool. {% hint style="info" %} Graphical sessions leave a **video recording and no command list**. There is nothing to grep and nothing to filter: text-level auditing and command filtering exist only for terminal protocols. Plan your evidence around the recording — see [Session recordings](/pam/administration/audit/recordings). {% endhint %} Two more limits are specific to graphical sessions: * **Session sharing is not available.** A user cannot hand an RDP, VNC, or database session to a colleague; sharing works only for SSH and Telnet in the web terminal. An auditor can still watch an RDP session live — see [Live monitoring](/pam/administration/sessions/live-monitoring). * **Automatic password rotation does not cover Windows RDP accounts.** Rotation is supported over SSH and for the database platforms; a Windows account reached only by RDP has to be rotated another way. See [Rotation](/pam/administration/accounts/rotation). ## Before you start * The asset registered on a Windows platform, with the **RDP** protocol and its port. See [Platforms](/pam/administration/assets/platforms). * An account on the asset, registered in the solution. * An authorization granting the user the asset, the account, the **RDP** protocol, and the **Connect** action — plus **Clipboard › Copy** and **Clipboard › Paste** if they need copy and paste, and the **Transfer** actions if they need to move files. See [Authorizations](/pam/administration/access/authorizations). * The graphical connector online. Check **System settings › Components** and confirm its **Load status** is **Normal**; an offline connector fails every graphical session on the platform. ## Steps 1. Set the display size first, under **Personal settings › Web terminal › Graphics**. Changing it mid-session means reconnecting. Multiple monitors are supported. 2. Open the device access list, right-click the asset, and choose to connect. 3. Select the **RDP** protocol in the left-hand menu of the **Connect** dialog, and choose the account. 4. Set the connection method — **Web** for the in-browser desktop, or the client option to hand the session to the local RDP client — and click **Connect**. 5. If the connection fails during negotiation rather than at the credential, change the asset's platform variant. This is covered below and it is the first thing to try, not the last. ## Choosing the Windows platform variant Three Windows platforms exist, with identical protocol lists. They differ only in how the RDP security layer is negotiated: | Platform | Use it for | | --------------- | ------------------------------------------------------- | | **Windows** | Servers and workstations in general | | **Windows-RDP** | Hosts that require classic RDP negotiation, without TLS | | **Windows-TLS** | Hosts that require RDP over TLS | {% hint style="warning" %} The variants exist because RDP security negotiation differs between Windows versions and server configurations. When a graphical connection fails to negotiate, switching the asset between **Windows**, **Windows-RDP**, and **Windows-TLS** is the first adjustment to test — before you look at credentials, firewalls, or the connector. {% endhint %} ## What you should see The browser opens a desktop at the resolution you selected, already logged in as the chosen account — the user is never prompted for the Windows password. If watermarking is enabled, the overlay with user and asset identity is visible across the desktop and stays in the recording. ## How to verify it worked 1. Do something visually identifiable on the desktop, then disconnect deliberately rather than closing the tab. 2. Open **Audit › Sessions**, switch to **Historical sessions**, and confirm a record exists with protocol **RDP**, the account you used, and a duration that matches the session. 3. Click **Replay** and confirm the identifiable action is in the video, and that playback runs to roughly the recorded length. A recording that never starts and one that stops early are different faults. 4. If watermarking is a requirement, confirm the overlay is present in the replay — not only on your screen during the session. 5. If you changed the platform variant, connect once more and confirm you now get past negotiation. Do it on the asset you changed: the variant is a property of the asset's platform, so other Windows assets are unaffected. ## Common errors | Symptom | Cause | Fix | | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | The connection fails while negotiating, before any credential prompt | The asset's RDP security layer does not match the platform variant | Switch the asset between **Windows**, **Windows-RDP**, and **Windows-TLS** | | The session freezes after a few idle minutes and needs a reconnect | Chrome's **Memory saver** suspended the browser tab holding the session | In Chrome, **Settings › Performance › Memory saver**, set **Balanced** or turn it off, then restart the browser | | "The session has ended because it conflicts with another session" | Someone else with permission to the same asset took the access over | Find who in **Audit › Sessions**; nothing is broken, the access was superseded | | The watermark is missing when using the local RDP client | The watermark is drawn by the graphical connector and does not always reach a native RDP client | Use the web session where the watermark is a compliance requirement | | **Replay** is greyed out on a session that clearly happened | The session was too short to be counted as a successful connection | Nothing to recover; expect very short sessions to have no replay | | A recording will not play outside the console | The replay format needs the player | Use the DataDike PAM video player for offline playback | | Account discovery on a Windows host fails with "The connection plugin 'rdp' was not found" | The host has no SSH protocol entry, which the collection job needs | Add port **22** to the host's **Protocols** list | | Every graphical session fails at once | The graphical connector is offline or saturated | Check **Load status** in **System settings › Components**; add another instance if it is consistently at **High load** | ## Field reference Display settings, at **Personal settings › Web terminal › Graphics**: | Field | Options | | ---------- | --------------------------------------------------------------------- | | Resolution | **AUTO** (fits all monitors), 1024x768, 1366x768, 1600x900, 1920x1080 | Listener ports, part of the TCP port policy. These are the ports the connector listens on for native clients, not the ports on the asset: | Field | Default | Notes | | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------ | | RDP port | 3389 | Keeps the Microsoft convention. In hardened environments, move it to a non-standard port and restrict it at the firewall | | VNC port | 15900 | Deliberately not 5900, to avoid clashing with a VNC server on the same host | Graphical-session settings, at **System settings › Security › Sessions**: | Field | What it does | | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | Watermark | Overlays user and asset identity on remote desktop sessions and their recordings. Enabled by default | | Allow users to view asset session information | Shows the number of active sessions on the asset in the account-selection dialog. **RDP only** | | Session share | Global switch for session sharing. It has no effect on RDP, VNC, or database sessions, which cannot be shared | | Max idle time (minute) | Disconnects a session idle for longer than this. Default 30 | | Max online time (hour) | Disconnects a session open longer than this | ## Related pages * [Platforms](/pam/administration/assets/platforms) — the three Windows variants and what else a platform decides * [Session recording](/pam/administration/sessions/recording) — what a graphical session captures, and where it goes * [Session recordings](/pam/administration/audit/recordings) — replaying and downloading the video * [Live monitoring](/pam/administration/sessions/live-monitoring) — watching, pausing, and ending a live session * [Ports and protocols](/pam/reference/ports) — the port used to reach each platform # Web sessions Register a web application as an asset so the solution opens it in a browser and types the credential for the user, with the session recorded. ## What this is and when to use it A web session gives a user access to a web application — a firewall console, an appliance admin page, a SaaS portal — without ever handing them the password. The solution opens the application's login page in a controlled browser, fills in the stored credential, and records what happens next. Use it for any system whose only administrative interface is a web page. What the user gets is a link they can click; what they do not get is the account. {% hint style="danger" %} Web access needs an **additional Windows machine**. No web session runs on the PAM server itself — that is a deliberate security boundary, not a limitation to be worked around. Without that machine, a Website asset can be registered but not connected to. {% endhint %} ## Before you start * A **Windows Server 2022 or 2025** machine to run the browser, with **OpenSSH installed and running**. * The **exact URL of the application's login screen** — not its home page, not a landing page that redirects. * The credential the application actually expects, ready to register as a managed account. * If you intend to use autofill: the HTML identifiers of the login fields, collected in advance from the page itself. ## Steps 1. Open the application's login page in your own browser first, and keep it open. You will need it to read the field identifiers. 2. In the console, open **Environment › Assets** and click **Create**. Choose the **Web** tab, then **Website**. 3. Fill in the **Name** — follow a naming convention someone else can read — and the **URL** of the login screen. 4. Under **Protocol**, confirm the protocol is `http(s)` and check the port shown. See the warning below on how the port is really set. 5. Choose the **Node** — the folder of the asset tree this asset is filed in. See [Folders and tags](/pam/administration/assets/folders-and-tags). 6. Under the selector settings, pick the autofill mode: **Disabled**, **Basic**, or **Script**. The three are described below. 7. Under **Account**, click **Add** and register the credential the application itself expects — the real username and password used at that login screen. Mark **Privileged account** if it carries elevated rights, and leave **Active** enabled. 8. Optionally add **Tags** for categorization and a **Comment**. Keep the comment free of secrets. 9. Leave **Active** enabled so the asset is available, then **Save** — or **Save and continue adding** if you have more accounts to attach. 10. Open **Authorizations** and either edit an existing policy or create one, associating the users or groups with the new website. Until this is done, the asset exists and nobody can reach it. {% hint style="warning" %} **The URL and the port are not independent fields.** To change the port, edit it inside the **URL**; the **Protocol** section follows the change. Changing `https://system.example.local:8088/dashboard` to `https://system.example.local:8443/dashboard` makes the Protocol section show `8443` as well. Do not edit the two as if they were separate parameters. {% endhint %} {% hint style="warning" %} **The URL must point directly at the authentication screen.** Autofill and auditing both depend on it. A URL that lands on a home page, a marketing page, or anything that redirects before the login form appears will break the credential injection. {% endhint %} ## Autofill modes | Mode | Use it when | What happens | | ------------ | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- | | **Disabled** | You only want the session audited | The user types the credential themselves. The solution records and monitors, nothing more | | **Basic** | The login is simple — username, password, and button on one screen | The solution locates the three elements by selector and fills them in | | **Script** | Authentication happens in stages — separate screens or sections for username and password, or the form sits inside an `iframe` | An ordered list of actions is executed, step by step | ### Basic selectors Open the login page, right-click the field, and choose **Inspect**. Read the identifier off the HTML for each of the three elements — username field, password field, login button — and enter it in the corresponding selector field. Prefer identifiers in this order: 1. `ID` 2. `NAME` 3. `XPath` Typical values look like `id=username`, `name=password`, `id=login_button`. `XPath` is last because it describes a position in the page structure, and page structures change. ### Script mode Selecting **Script** reveals a field for a JSON script. Each entry is one action, executed in the order given. | Command | What it does | | -------------- | --------------------------------------------- | | `select_frame` | Switches into an `iframe` | | `type` | Types into a field | | `click` | Clicks a button | | `sleep` | Waits, in seconds, for the next stage to load | Two variables carry the credential into the script: `{USERNAME}` for the username and `{SECRET}` for the password. Never write a literal password into the script. ```json [ { "step": 1, "command": "select_frame", "target": "id=iframe_id", "value": "" }, { "step": 2, "command": "type", "target": "name=username", "value": "{USERNAME}" }, { "step": 3, "command": "click", "target": "id=next_button", "value": "" }, { "step": 4, "command": "sleep", "target": "5", "value": "" }, { "step": 5, "command": "type", "target": "name=password", "value": "{SECRET}" }, { "step": 6, "command": "click", "target": "id=submit_button","value": "" } ] ``` That script switches into the `iframe`, types the username, clicks **Next**, waits five seconds for the second screen to load, types the password, and submits. The `sleep` step is what makes a staged login work — without it the next `type` runs against a field that does not exist yet. ## What you should see The saved asset appears in the inventory under the **WEB** group, with the platform badge **Website** and the state `ACTIVE`. Its details show the protocol as `http(s)` on the port taken from the URL. Protocol settings may be **inherited from the platform**. Where that is the case, the gear icon next to the protocol lets you view or adjust the inherited value. ## How to verify it worked Registration proves nothing on its own. Verify by connecting: 1. Sign in as a user the authorization covers — not as the administrator who created the asset. That is the only way to confirm the authorization is right. 2. Open the website from the device access list. The browser session should land on the application **already logged in**. If it stops on the login page with fields filled but not submitted, the button selector is wrong; if the fields are empty, the field selectors are wrong or the URL is not the login page. 3. Confirm the session is listed in the audit trail with the account that was used. A web session that works but is not recorded means the URL is bypassing the authentication screen. ## Common errors | Symptom | Cause | Fix | | ------------------------------------------------ | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | Connection fails immediately | The Windows host that runs the session has no network route to the target application | Place that host in a network able to reach the application | | Session opens on the login page, nothing filled | Autofill is **Disabled**, or the URL does not land on the login form | Set the mode to Basic or Script, and point the URL directly at the authentication screen | | Fields fill but login never submits | The login button selector is wrong | Re-inspect the button and prefer its `ID` over an `XPath` | | Username is typed, password field is never found | Staged login being handled in **Basic** mode | Switch to **Script** and add `select_frame` and `sleep` steps | | Port change has no effect | The port was edited in the Protocol section but not in the URL | Edit the port inside the **URL**, then confirm the Protocol section shows the same value | | No web session starts at all | No Windows machine, or OpenSSH not running on it | Provision the Windows Server 2022/2025 host and start OpenSSH | ## Field reference | Field | Meaning | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | **Name** | Identifier inside the console. Use a readable convention | | **URL** | The application's login page. Also determines the effective port | | **Protocol** | `http(s)` plus the port. Follows the URL; may be inherited from the platform | | **Node** | The folder of the asset tree the asset is filed in. Used by authorizations, automations, and sync policies to target groups of assets | | **Selector** | Autofill mode: Disabled, Basic, or Script | | **Account › Name** | How the credential is identified in the console | | **Account › Username** | The username the application expects | | **Account › Privileged account** | Marks the credential as holding elevated rights | | **Account › Authentication type** | Set to **Password** for a website | | **Tag** | Optional categorization of the asset | | **Active** | Must stay enabled for the asset to be available | | **Comment** | Informational. Do not put sensitive information here | ## Related pages * [Asset inventory](/pam/administration/assets/inventory) * [Platforms](/pam/administration/assets/platforms) * [Managed accounts](/pam/administration/accounts/managed-accounts) * [Authorizations](/pam/administration/access/authorizations) * [Connection methods](/pam/administration/sessions/connection-methods) # Database sessions Brokered access to eleven database platforms, through the web console or a native client, with query recording and command control. ## What this is and when to use it The solution brokers access to databases the same way it brokers access to a server: it holds the credential, opens the session on the user's behalf, records the queries, and applies command control. Two paths reach the same database: * the **web console**, where the query interface runs in the browser * a **native client** — PL/SQL Developer, Oracle SQL Developer, MongoDB Compass, SQL Server Management Studio, and others — connecting through the solution The second is what makes database access practical for a DBA, who is not going to give up their tooling. ## Before you start * The database registered as an asset, on the matching platform. * The credential registered as a managed account. * For Oracle, the **SID** or **Service Name** configured. ## Supported platforms | Database | Note | | -------------- | -------------------------------------------------------- | | **Oracle** | Requires SID or Service Name | | **MySQL** | | | **MariaDB** | Its own platform, separate from MySQL | | **PostgreSQL** | | | **SQLServer** | Microsoft SQL Server | | **MongoDB** | Document database | | **Redis** | Versions before 6 | | **Redis6+** | Version 6 and later, which have their own users and ACLs | | **ClickHouse** | Columnar analytical database | | **DB2** | IBM Db2 | | **Dameng** | DM database | {% hint style="info" %} **The port is configurable.** The value shown on the Platforms screen is only the product's initial suggestion. The effective port is set in each asset's registration and can be anything, which covers environments that do not use the database's conventional port. {% endhint %} {% hint style="warning" %} Choosing between **Redis** and **Redis6+** matters. From version 6 Redis has per-user authentication; picking the wrong platform prevents login with a named credential. {% endhint %} ## Notes per database **MySQL and PostgreSQL** — fully supported, with SQL command recording and the web database interface. **SQL Server** — supported from version 2012. Integrates with the `GB18030` character set, and handles multi-line queries and HA clusters. **Oracle** — fully supported. Requires SID or Service Name configured for connection by TNSNames. Suited to long queries and PL/SQL applications. Oracle does not accept insecure connections; when that enforcement is enabled, it needs an adjustment on the Oracle side. ## How to verify it worked 1. Open a session to the database from the console and run a trivial query, `SELECT 1` or its equivalent. 2. Open **Audit › Sessions** and confirm the session is there. 3. Open the session's commands and confirm the query you ran was recorded. If the session appears but the query did not, recording is not capturing that protocol. 4. Repeat from a native client if that is how the team will actually work. The web console succeeding does not prove the native path does. ## Common errors | Symptom | Cause | Fix | | --------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------ | | Oracle connection fails immediately | SID or Service Name not configured | Set it in the asset registration | | Oracle refuses the connection when encryption is enforced | Oracle does not accept insecure connections | Adjust the enforcement on the Oracle side | | Redis login with a named user fails | The asset is on **Redis** instead of **Redis6+** | Switch the platform | | The connection is refused although the host is reachable | The database does not listen on the conventional port | Set the effective port in the asset registration | | MariaDB behaves unexpectedly under MySQL | It was registered on the MySQL platform | MariaDB has its own platform. Move it | ## Related pages * [Platforms](/pam/administration/assets/platforms) * [Asset inventory](/pam/administration/assets/inventory) * [Connection methods](/pam/administration/sessions/connection-methods) * [Session recording](/pam/administration/sessions/recording) * [Command inspection](/pam/administration/access/command-filtering) # File transfer The four ways files move between a user's workstation and a protected asset — in-browser explorer, bulk upload, an external SFTP client, and the CLI — and what each one records. ## What this is and when to use it Files reach a protected asset through the solution, not around it. Every path below carries the same two properties: the user never holds the asset's credential, and every upload and download is written to the audit trail with a retrievable copy of the file. On Linux assets the transfer runs over **SFTP**, and by default it uses the same port as SSH — port **22** on the asset. Four paths exist, and they are not interchangeable: | Method | Where | Upload | Download | Reach | | ------------------------ | ---------------------------- | ----------------------- | -------- | --------------------------------------- | | **File explorer** | Browser, new tab | Yes | Yes | Any directory the account has rights to | | **File transfer** (bulk) | Browser, console page | Yes, many files at once | **No** | `/tmp/` only | | **SFTP client** | FileZilla, WinSCP, MobaXterm | Yes | Yes | Any directory the account has rights to | | **SFTP over CLI** | Terminal | Yes | Yes | Any directory the account has rights to | {% hint style="warning" %} Two different ports are involved and confusing them is the most common mistake here. Port **22** is the asset's own SSH/SFTP port, used by the solution to reach the target. Port **2222** is the solution's own SFTP listener, which is what an external client connects to. An SFTP client pointed at port 22 of the PAM address will not work. {% endhint %} ## Before you start * The user needs the **Transfer** actions in the authorization rule that grants them the asset: **Upload**, **Download**, and **Delete** are granted separately. Without them the connection succeeds and the file operation is refused. See [Authorizations](/pam/administration/access/authorizations). * The asset's SFTP port must be reachable from the solution. * An account on the asset with filesystem rights to the directories in question. The solution enforces its own permissions on top of the operating system's; it does not override them. ## In-browser file explorer The fullest option: a file manager with free navigation, upload, and download. There are two ways in, and they land in the same place: * From the device access list, right-click the asset, choose to connect, select the **SFTP** protocol, pick the account, set the connection method to **Web**, and click **Connect**. * From **Cockpit › File explorer**, then expand the asset tree in the **Places** sidebar on the left and select the device. Once the explorer is open: * **Upload** — navigate to the destination directory, then either drag files into the main panel, or right-click an empty area of the file panel and choose **Upload files**. * **Download** — right-click the file and choose **Download**, or double-click it. ## Bulk upload Use **Cockpit › File transfer** when you need to push many files to many assets at once and do not need to retrieve anything. 1. Open **Cockpit › File transfer**. 2. In the **Asset tree** on the right, select the target asset from the list of available devices. 3. In **Account information**, enter or select the account the transfer will run as. 4. Check **Upload to directory**. It shows `/tmp/` and it is fixed. 5. Drag the files into the upload area, or use **click here to upload** to pick them from your workstation. 6. Click **Transfer**. 7. Watch the **Pending** section, which lists each file with its success or failure status. {% hint style="warning" %} This method **uploads only** — there is no download. And the destination is locked to `/tmp/` on the asset; you cannot choose another directory. If you need a different path, or you need to fetch a file, use the file explorer instead. {% endhint %} {% hint style="info" %} Each file may be up to **200 MB**. The underlying limit is the `CLIENT_MAX_BODY_SIZE` parameter, whose default is `4096m`; raising or lowering the per-file ceiling is a change to the deployment, so ask the vendor before relying on a different value. {% endhint %} ## External SFTP client Point any SFTP client at the solution itself rather than at the asset. You authenticate with your **own** PAM credentials — never the asset's — and MFA is requested if it is enabled on your profile. What you then see is a directory tree of the assets and accounts available to you: navigate to the target server, pick the account, and transfer normally. | Parameter | Value | | ------------ | ------------------------- | | **Protocol** | SFTP | | **Host** | The solution's IP address | | **Port** | 2222 | | **User** | Your PAM username | | **Password** | Your PAM password | * **FileZilla** — enter `sftp://` as the host, port `2222`, your PAM username and password, then **Quickconnect**. Transfer by drag-and-drop. * **WinSCP** — protocol **SFTP**, host the PAM address, port `2222`, your PAM credentials, then **Login**. * **MobaXterm** — the SFTP panel appears automatically on the left when you connect, so files can be dragged in either direction. ### From the command line ``` sftp -P 2222 user@pam_address ``` | Command | Action | | ----------- | ------------------ | | `ls` | List files | | `cd dir` | Change directory | | `get file` | Download a file | | `put file` | Upload a file | | `rm file` | Delete a file | | `mkdir dir` | Create a directory | ## File conflict strategy When a file of the same name already exists at the destination, the behaviour is a per-user preference set under **Personal settings › Preferences › File conflict strategy**: | Strategy | Result | | ------------- | ---------------------------------------------- | | **Overwrite** | Replaces the existing file | | **Skip** | Keeps the original, discards the incoming file | | **Rename** | Keeps both; the incoming file gets a suffix | ## How to verify it worked Do not trust the progress indicator alone — it confirms the upload reached the solution, not that the file landed on the asset. 1. Open **Audit › File transfers**. The transfer must appear as its own record, with the user, the asset, the account used, the operation (**Upload** or **Download**), and the file name. 2. Use the record's action button to **download a copy of the transferred file**, and confirm it is the file you meant to send. This is the check that proves content, not just intent. 3. For a bulk upload, reconnect through the file explorer and list `/tmp/` on the asset. A file that is absent there but shows as successful in **Pending** points at the destination account's rights, not at the transfer. A transfer that succeeded but produced no audit record is a finding worth investigating: every method above is supposed to record. ## Common errors | Symptom | Cause | Fix | | ------------------------------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- | | Transfer is refused mid-session | The **Transfer** actions were not granted in the authorization | Grant Upload, Download, or Delete as needed on the rule | | SFTP client cannot connect at all | Pointed at port 22 of the PAM address, or at the asset directly | Use the PAM address on port **2222** | | Client connects, then rejects the login | The asset's credential was used instead of your own PAM credential | Authenticate with your PAM username and password; the asset account is chosen afterwards, inside the tree | | Login is accepted then hangs | MFA is enabled on your profile and the prompt was not answered | Complete the MFA challenge the client presents | | No download option anywhere on the screen | You are on the bulk **File transfer** page, which is upload-only | Use the **File explorer** instead | | Upload cannot be placed in the intended directory | Bulk transfer is fixed to `/tmp/` | Use the file explorer, which can reach any directory the account has rights to | | Upload fails on a large file | The file exceeds the per-file limit, 200 MB by default | Split the file, or have the limit reviewed for the deployment | | A file of the same name silently did not change | The conflict strategy is set to **Skip** | Change the strategy to Overwrite or Rename | ## Related pages * [Authorizations](/pam/administration/access/authorizations) * [Connection methods](/pam/administration/sessions/connection-methods) * [Asset inventory](/pam/administration/assets/inventory) * [Managed accounts](/pam/administration/accounts/managed-accounts) * [Command filtering](/pam/administration/access/command-filtering) # Session recording Configure what is captured during a session and where it is kept — the object storage backend for replays, the separate store for commands, watermarking, and how retention of metadata differs from ret ## What this is and when to use it Every session the solution brokers is recorded, for every protocol, with no per-session switch to forget. This page is about **configuring** that: what is captured for each protocol, where the files are written, what the watermark says, and how long any of it survives. Finding and replaying a recording afterwards is a different job, on a different screen — see [Session recordings](/pam/administration/audit/recordings). ### Two stores, not one The distinction matters as soon as you start configuring, because the two are configured separately and can live in different places: | Store | Holds | Default location | | ------------------- | ------------------------------------------------------------------------------------------ | ------------------------------- | | **Object storage** | The replay itself — screen video for graphical sessions, terminal replay for text sessions | The PAM server's own filesystem | | **Command storage** | The commands typed in terminal and database sessions, as searchable text | The PAM database | ### What each protocol leaves behind | Protocol | Replay | Searchable commands | | ------------------------------- | --------------------- | ------------------------------------------------------- | | SSH, Telnet | Terminal replay | Yes | | RDP, VNC, RemoteApp, VirtualApp | Screen video | No | | Database | Replay of the session | Yes — the queries executed | | SFTP and file transfer | — | Not commands, but a retrievable copy of each file moved | {% hint style="info" %} Replays are compressed and optimized before they are stored, in local storage and in an external backend alike, so the disk figures are lower than raw screen capture would suggest. Graphical sessions still consume far more space than terminal sessions — size your storage from the RDP traffic, not the SSH traffic. {% endhint %} ## Before you start * The **SYSADMIN** profile. * A decision on where recordings will live, made **before** you go to production. Sessions recorded to the local disk are not migrated when you later add an external backend. * If you are pointing at an object store: the bucket or container, credentials scoped to it, and TLS available on the endpoint. * A retention decision for the files, separate from the retention setting in the console. See the warning under Retention. ## Configuring where replays are stored 1. Open **System settings › Storage › Object storage**. Two entries exist and neither can be deleted: * **default** — type **Server**, the local filesystem of the PAM server. This is the active default after installation. * **null** — type **Null**, described as *Do not save*. It discards recordings instead of storing them. 2. Click **Create** and choose the backend type. The supported types are **S3** (Amazon S3 and any S3-compatible service such as MinIO or Wasabi), **Ceph**, **Swift**, **OSS**, **Azure**, **OBS**, **COS**, **SFTP**, **Server**, and **Null**. 3. Fill in the endpoint, bucket, and credentials for the backend, and give it a **Description** that says which sessions it is meant to hold. 4. Set the new backend as **Default**. Only one backend is the default at a time, and it is the one new recordings are written to. {% hint style="danger" %} Do not leave the **default** local backend in place in production. It has no redundancy, it fills the PAM server's own disk, and it does not scale. Move to an external object store as early as you can, and give the bucket server-side encryption and a policy that admits the solution only — `GetObject`, `PutObject`, `DeleteObject`, `ListBucket`, nothing wider. {% endhint %} To deliberately **not** record a class of sessions — a lab environment, for instance — the mechanism is the **null** backend rather than a per-session toggle. Be explicit about that decision: a session recorded to `null` still produces a session record, so the audit list shows an entry with no replay behind it, which is indistinguishable at a glance from a recording that failed. ## Configuring where commands are stored 1. Open **System settings › Storage › Command storage**. 2. The list is **empty by default**, and that is not a misconfiguration: with no backend defined, commands are stored in the solution's own database. 3. Add a backend — Elasticsearch, for example — when command search has become slow. At high session volumes an external index is markedly faster to search than the database, and it takes the command history off the database's growth curve. ## Configuring the watermark The watermark overlays identity onto the session and into its recording, so a screenshot or a phone photograph carries the identity of whoever took it. 1. Open **System settings › Security › Sessions**. 2. **Watermark** is enabled by default. It applies to sessions in the browser and to the stored recording. 3. Edit **Watermark session content** to control what the overlay says, using the variables below. They are substituted with real session data at connection time. | Variable | Substituted with | | ----------------- | --------------------- | | `${userId}` | User ID | | `${name}` | User's full name | | `${userName}` | User's login name | | `${assetId}` | Asset ID | | `${assetName}` | Asset name | | `${assetAddress}` | Asset address | | `${currentTime}` | Current date and time | Some usable templates: ``` ${name} (${userName}) ${assetName} ${assetAddress} User: ${name} (${userId}) accessing ${assetName} Access recorded on ${currentTime} by ${name} ${assetName} - address: ${assetAddress} - viewed by ${userName} ``` {% hint style="warning" %} The watermark is drawn by the connector that brokers the session. It is reliable for SSH and Telnet and for graphical sessions in the browser, but a watermark on an RDP session **does not always reach a native RDP client**. If the watermark is a compliance control rather than a deterrent, keep those users on the browser session — see [Connection methods](/pam/administration/sessions/connection-methods) for how to remove the client option. {% endhint %} ## Recording does not depend on where the asset is The recording happens at the connection broker, not on the target. Everything the user does passes through it, so what gets recorded is the same whether the asset sits on the same network as the solution or somewhere the solution cannot reach directly. | Where the asset is | How the session is reached | What is recorded | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------- | | Same network | Direct | Full session, commands, transfers | | Segmented network | Through a [gateway](/pam/administration/connectivity/gateways) in a [proxy](/pam/administration/connectivity/proxy) zone | The same | | Remote site, no inbound route | Through a [broker](/pam/administration/connectivity/broker), where the remote side dials out | The same | | A single isolated machine | Through a [connector](/pam/administration/connectivity/connectors) that dials out from the machine itself | The same | This matters for two cases that are otherwise hard to audit: * **A supplier working on a system in their own network.** The session is brokered and recorded like any other. There is no agent on the target and no inbound firewall rule to the supplier's side. * **A branch or a remote site.** Nothing has to be deployed per site beyond the component that dials out, and the recordings all arrive in the same store, under the same retention. The user's own network position changes nothing either. A session opened from the web terminal is recorded identically to one opened with a native client through the broker. ## Retention **System settings › Retention › Log record** holds the retention windows the nightly cleanup jobs enforce: | Field | Default | Covers | | -------------------------- | ------- | ------------------------------------------------------------------------- | | Session log retention days | 200 | Session metadata: user, asset, account, start and end, duration, protocol | | FTP log retention days | 180 | File transfer records | {% hint style="danger" %} **Session log retention days controls metadata in the database, not the recording files.** Raising it does not keep replays longer, and lowering it does not reclaim storage. The lifecycle of the actual files is set on the bucket or container itself. Configure both, or you will end up with either orphaned files nobody can find or session records whose evidence has already expired. {% endhint %} ## How to verify it worked Prove the pipeline on sessions you create for the purpose — one per protocol you care about, because what is captured differs by protocol. 1. Open an SSH session, type an identifiable command, and disconnect. 2. Open an RDP session, do something visually identifiable, and disconnect. 3. In **Audit › Sessions › Historical sessions**, confirm both sessions offer **Replay**, and play each one back. 4. Confirm the watermark is visible **in the replay**, not merely on screen during the session. 5. Confirm the SSH session has a command list and the RDP session does not — that is the expected asymmetry, not a fault. 6. If you have just switched to an external backend, look in the bucket and confirm new objects arrived for these sessions. This is the step that catches wrong credentials and a wrong endpoint: the console reports the backend as configured while recordings keep going to the old default. 7. Watch the PAM server's own disk usage for a few days after the switch. It should stop growing at the rate it did before. ## Common errors | Symptom | Cause | Fix | | --------------------------------------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | The PAM server's disk fills up | Recordings are still going to the local **default** backend | Configure an external object storage backend and set it as default | | Retention was reduced but storage never shrinks | The retention setting covers metadata only | Set a lifecycle policy on the bucket or container | | A session record exists with no replay | The session was routed to the **null** backend, or recording failed | Check which backend is default; a `null` destination looks identical to a failure from the audit list | | The watermark is missing in a session opened with a native RDP client | The overlay does not always reach a native client | Route those users to the browser session | | No command list for an RDP or VNC session | Graphical protocols produce no command record at all | Use the replay; there is nothing textual to search | | **Replay** greyed out on a very short session | The session was too short to count as a successful connection | Expected; nothing to recover | | Command search is slow at scale | Commands are in the solution's database | Add an external Command storage backend such as Elasticsearch | | Storage grows far faster than expected | Graphical sessions dominate the volume | Size and alert on the bucket from RDP and VNC usage, not from SSH | ## Related pages * [Session recordings](/pam/administration/audit/recordings) — finding, replaying, and downloading a recording * [Audit trail](/pam/administration/audit/audit-trail) — the records kept alongside the replay * [Live monitoring](/pam/administration/sessions/live-monitoring) — watching a session while it is still running * [RDP sessions](/pam/administration/sessions/rdp) — why a graphical session has no command list * [File transfer](/pam/administration/sessions/file-transfer) — the copies kept of files that moved during a session # Live monitoring and termination Watch, pause, resume, or cut off a privileged session while it is still running, disconnect a console login, and let users share a live terminal with a colleague. ## What this is and when to use it Authorized profiles can act on a privileged session **while it is happening**. From the list of active sessions an administrator or auditor can watch the session, freeze it, hand control back, or drop it, and follow the commands and file transfers as they occur. Use it when something is in progress that you need to see or stop: a change window you are supervising, an unfamiliar third party at work, an alert on a session that is still open. Three things are easily confused, and the distinctions decide which screen you want: | You want to | Go to | | ------------------------------------------------------------- | ---------------------------------------------------------- | | Act on a session in progress | **Audit › Sessions › Online** — this page | | Replay a session that has ended | [Session recordings](/pam/administration/audit/recordings) | | Disconnect someone from the console itself, not from an asset | **Audit › Console › Online users** — below | Session **monitoring** and session **sharing** are also different things. Monitoring is something an auditor does to someone else's session, under RBAC. Sharing is something the session's own owner does, by handing out a link. {% hint style="info" %} Every intervention is itself audited. Watching, pausing, resuming, and disconnecting are written to the audit trail with the operator, the session affected, and the time — so a monitor's actions are as traceable as the monitored user's. {% endhint %} ## Before you start * A role that grants live-session permissions. Monitoring someone else's session is gated by RBAC, and without it the sessions of other users are not visible or actionable. See [Roles](/pam/administration/identities/roles). * An understanding of the blast radius. **Pause**, **Resume**, and **Disconnect** take effect immediately on the monitored user's screen. Keep these permissions on administration and audit profiles. * If your policy requires it, the original user's approval before a monitor may join a session — this can be turned on so that watching is not silent. * For sharing, **Session share** must be enabled at **System settings › Security › Sessions**, and the user needs the **Share** action in the authorization that grants them the asset. See [Authorizations](/pam/administration/access/authorizations). ## Acting on a live session 1. Open **Audit › Sessions › Online**. The list shows, in real time, every active session with its user, target asset, account, protocol, authentication method, and start time. 2. Find the session and use the **Operation** column, or the **More actions** menu. | Action | What it does | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Watch** | Opens the live session read-only, as a shadow. You see exactly what the user sees and cannot interfere | | **Pause** | Suspends the session immediately. The user's screen freezes and no input is accepted while it stays paused — this is what buys you time to assess something suspicious without destroying the session | | **Resume** | Returns control to the user from the point where it was interrupted | | **Disconnect** | Ends the session at once, dropping the user's connection to the asset | {% hint style="warning" %} **Pause** is the tool for an ambiguous situation and **Disconnect** is the tool for a decided one. Pausing preserves the session and everything in it while you decide; disconnecting ends it and the user has to start again. {% endhint %} While you are watching, the session's content keeps flowing into the audit records: commands as they are typed, uploads and downloads as they happen, and the start, pause, resume, and end events with the identity of whoever caused each one. See [Audit trail](/pam/administration/audit/audit-trail). ## Sharing a live session with a colleague Sharing is user-initiated collaboration rather than oversight: the owner of a session invites someone in, to ask for help or to be observed. {% hint style="warning" %} Sharing works **only for SSH and Telnet sessions opened in the web terminal**. RDP, VNC, and database sessions cannot be shared. An auditor can still watch those live from **Audit › Sessions › Online**. {% endhint %} From an active web terminal session: 1. Click the share icon on the right of the session window. 2. Set how long the link stays valid. 3. Choose the access type — **Read and write**, marked with a pencil, lets the guest type; **Read only**, marked with an eye, lets them watch. 4. Optionally set a verification code the guest must enter as well as holding the link. 5. Create the link and send it to the colleague. The share icon then shows how many people are in the session. The owner can disconnect any guest at any moment, and closing the link stops new joins. Commands are attributed to each participant individually in the audit records, so a read-and-write share does not blur who did what. ## Disconnecting a console login **Audit › Console › Online users** is about the solution's own web interface, not about asset sessions. It lists who is signed in, how they authenticated, and when, with a **Disconnect** button per user and bulk options under **More actions**. Two limits are worth knowing before you go looking for a user who is not listed: * Only users **connected over the web** appear here. * You cannot disconnect your own current session from this screen. ## Automatic termination Some terminations do not need an operator. At **System settings › Security › Sessions**: | Field | Default | What it does | | -------------------------------- | ------- | ------------------------------------------------------------------------------------------- | | Max idle time (minute) | 30 | Disconnects a session idle for longer than this | | Max online time (hour) | — | Disconnects a session open longer than this, active or not | | Session expire at browser closed | — | Ends the user's console session when they close the browser, regardless of the idle timeout | ## How to verify it worked Verify with a real session rather than by reading the permission list. Use a second browser profile, or a test user, so you can see both sides: 1. As the test user, open a session to an asset. It must appear in **Audit › Sessions › Online** within seconds. If it does not, either RBAC is not granting you other users' sessions or the session is not being brokered. 2. **Watch** it, and type on the test user's side. The output must appear in your shadow view, and nothing you type must reach the asset. 3. **Pause** it. On the test user's side the screen must freeze and input must be refused. This is the check people skip, and it is the one that matters most in an incident. 4. **Resume** it and confirm control returns at the point of interruption, not at a new prompt. 5. **Disconnect** it and confirm the test user's connection drops and the session leaves **Online** for **Historical sessions** — where its recording becomes available. 6. Open [Audit trail](/pam/administration/audit/audit-trail) and confirm your four actions are logged against your own account, with the session identified. ## Common errors | Symptom | Cause | Fix | | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | You only see your own sessions in **Online** | Your role does not grant visibility of other users' sessions | Adjust the role — see [Roles](/pam/administration/identities/roles) | | **Watch** opens but nothing happens | The original user has to approve the monitor joining, and has not yet | Wait for the approval, or turn the requirement off if silent oversight is your policy | | A session stays under **Online** after the user disconnected | The session did not close cleanly | It has to be closed before its recording is offered; check the entry and end it from this screen | | The user reports "The session has ended because it conflicts with another session" | Another person with permission to the same asset took the access over | Identify who in **Audit › Sessions**; nothing is broken, the access was superseded | | The share icon is not in the session window | **Session share** is disabled globally, the user lacks the **Share** action, or the protocol is RDP, VNC, or a database | Enable sharing and grant the action; for graphical sessions, use auditor **Watch** instead | | A user you want to disconnect is not in **Online users** | They are not connected over the web, or they are you | Only web-connected users are listed, and you cannot disconnect your own current session | ## Field reference **Audit › Sessions › Online** columns: | Field | What it holds | | --------------------- | ------------------------------------------------ | | User | Who opened the session | | Target asset | The asset being accessed | | Account | The credential in use | | Protocol | SSH, RDP, VNC, database, and others | | Authentication method | How the user authenticated | | Start time | When the session began | | Operation | **Watch**, **Pause**, **Resume**, **Disconnect** | **Audit › Console › Online users** columns: | Field | What it holds | | --------------------- | ---------------------------------------- | | User | Who is signed in to the console | | Authentication method | How they signed in, for example password | | Login date | When they signed in | | Active | Whether the login is still active | | Operation | **Disconnect** | ## Related pages * [Session recordings](/pam/administration/audit/recordings) — the same sessions after they have ended * [Session recording](/pam/administration/sessions/recording) — what gets captured, and the watermark * [Audit trail](/pam/administration/audit/audit-trail) — where monitoring actions and session events are logged * [Authorizations](/pam/administration/access/authorizations) — where the **Share** action is granted * [Roles](/pam/administration/identities/roles) — the RBAC permissions that gate monitoring # Users and identities | Page | What it covers | | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Users and groups](/pam/administration/identities/users-and-groups) | Register the people who use the solution, group them, and control activation, expiry, and authentication requirements. | | [Roles and permissions](/pam/administration/identities/roles) | What a user may do inside the console, how organization roles differ from system roles, and how multi-tenancy scopes them. | | [LDAP and Active Directory](/pam/administration/identities/ldap-and-ad) | Authenticate console users against an LDAP or Active Directory server and provision their user records from directory attributes, including the group membership that drives authorizations. | | [Single sign-on](/pam/administration/identities/sso) | Delegate console login to a corporate identity provider over SAML2, OIDC, OAuth2, CAS, or Slack, and map the provider's attributes onto user records here. | | [Multi-factor authentication](/pam/administration/identities/mfa) | Require a second authentication factor for console access — globally, or per user — how a user enrols an authenticator app, and how to reset a factor someone has lost. | # Users and groups Register the people who use the solution, group them, and control activation, expiry, and authentication requirements. ## What this is and when to use it A user is someone who signs in to the solution — not a credential on a target. That distinction matters: the whole point of privileged access management is that a person authenticates as themselves and the solution supplies the target credential. Groups exist so that authorizations can be written once for a team instead of once per person. Prefer granting to groups; it is the difference between an access review that takes an hour and one that takes a week. {% hint style="info" %} Users can be local to the solution or provisioned from a directory. For LDAP, Active Directory, Radius, and OAuth, see [LDAP and Active Directory](/pam/administration/identities/ldap-and-ad). {% endhint %} ## Before you start * The **SYSADMIN** profile, or an organization administrator. * The groups you intend to use, created beforehand — assigning at creation is easier than retrofitting. ## Steps 1. Open **Users › Users**. 2. Click **Create**. 3. Fill the identity: **Name**, **Username** (unique — it is the login), and **Email**, which is used for notifications, password recovery, and directory integration. 4. Assign the **user groups**. These define the scope of permissions the user will receive through authorizations. 5. Assign the **profiles** — what the person may do inside the console. See [Roles and permissions](/pam/administration/identities/roles). 6. Set an **expiry date** if the access is temporary. Contractors and audits are the usual case, and setting it at creation is the only reliable moment. 7. Save. ## What you should see ![The Users screen](https://1085357737-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7xzJyi9JVzRwnV6JzUho%2Fuploads%2Fgit-blob-17f2cd5b82def62d2ba0ad1dd1a4a1499a4487de%2Fusers-and-groups.png?alt=media) **1** How many users the current filter returns. **2** One user row. The user appears in the list. Two columns tell you whether they can actually sign in: **Activation** and **Expired**. Both must be right — a user can be active and still blocked by an expiry date in the past. ## How to verify it worked 1. Ask the user to sign in, or sign in as them. 2. Confirm the console shows the areas their profile should allow. 3. Confirm they see the assets their authorizations grant. If the profile is right and no assets appear, the problem is the authorization, not the user. ## Bulk actions The **More actions** menu operates on the selected users: | Action | What it does | | ------------------- | --------------------------------------------------------------------------------------------------------------- | | Remove selected | Clears the selection or detaches from a grouping. **Does not delete the user** and does not change their status | | Deactivate selected | Blocks sign-in while keeping permissions and data. Reversible | | Activate selected | Restores access to previously deactivated users | | Delete selected | Permanently removes the users, their permissions, and associated data. **Not reversible** | | Update selected | Bulk-edits groups, profiles, tags, or applied policies | {% hint style="warning" %} **Remove** and **Delete** are not the same thing, and they sit next to each other. Remove clears a selection; Delete is irreversible. When in doubt, deactivate instead — it blocks access and keeps everything recoverable. {% endhint %} The toolbar also offers **Invite user**, to bring in a user from another organization, plus **Import** and **Export** in CSV and XLSX. ## Field reference The user table carries far more columns than are shown by default. The ones that decide behavior: | Field | What it means | | --------------------------------- | -------------------------------------------------------------------------- | | Username | The login used to authenticate. Must be unique | | Email | Notifications, password recovery, and directory integration | | User groups | The groups the user belongs to, which define permission scope | | Source | How the account was provisioned — Local, LDAP/AD, OAuth | | Organization role | Role at organization level, such as Operator or Auditor | | System role | Granular role in the solution, such as Global Administrator or Log Auditor | | Organization admin | May manage the whole organization | | Super admin | Maximum permission across the entire system, including global settings | | Activation | When off, no login is possible | | Expired | Blocks the account after the expiry date | | MFA | Whether multi-factor authentication is required | | MFA virtual bound | Whether an OTP app or device is linked | | Public key authentication allowed | Whether login by public key is permitted | | Needs password update | Forces a password change on the next sign-in | | Login blocked | Temporary block after failed attempts | | Valid | Internal flag indicating the account is in a consistent state | Informational columns include creation and update dates, last login, last API key use, last password change, creator, last updater, phone, Slack ID, tags, and a free-text comment. ## Common errors | Symptom | Cause | Fix | | ------------------------------------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | The user cannot sign in although the account looks fine | **Activation** off, or an expiry date in the past | Check both columns, not just activation | | Sign-in refused after several attempts | **Login blocked** after failed attempts | Wait for the block to lift, or clear it | | The user signs in but sees nothing | No authorization covers them | The user record is not where access is granted. See [Authorizations](/pam/administration/access/authorizations) | | A directory user reappears after deletion | The account is provisioned from a directory | Remove or disable it at the source, not here | ## Related pages * [Roles and permissions](/pam/administration/identities/roles) — what a user may do in the console * [Authorizations](/pam/administration/access/authorizations) — what a user may reach * [LDAP and Active Directory](/pam/administration/identities/ldap-and-ad) * [Multi-factor authentication](/pam/administration/identities/mfa) # Roles and permissions What a user may do inside the console, how organization roles differ from system roles, and how multi-tenancy scopes them. ## What this is and when to use it A role decides what a person may do **inside the console** — which screens they see and which actions they may take there. It is not an [authorization](/pam/administration/access/authorizations), which decides which assets and accounts they may reach. An auditor may hold a powerful role and no authorization at all; that is a normal and desirable configuration. There are two levels, and confusing them is the usual source of "why can they see that?": | Level | Scope | | --------------------- | ---------------------------------------------------------------------------- | | **Organization role** | Applies **only inside one organization**. Fully customizable | | **System role** | Applies across the solution — global administrator, log auditor, and similar | A user who belongs to several organizations can hold a different organization role in each. Being *Org Admin* in Development and *Org Auditor* in Production is a normal arrangement. ## Multi-tenancy The solution implements multi-tenancy by organization. Each organization is an isolated tenant inside a single instance. | Property | What it means | | -------------------- | ----------------------------------------------------------------------------------------------- | | Data isolation | Each organization has its own users, assets, accounts, permissions, and labels, fully separated | | Default organization | Always exists and cannot be removed. It is the instance's primary organization | | Context switching | The user switches organization from the selector at the top of the interface | | Audit isolation | An auditor of one organization sees only that organization's logs and sessions | | Resource scope | Roles, assets, and applications are restricted to the organization where they were created | | No sharing | Resources are not shared between organizations | ## Built-in organization roles ![The Roles screen](https://1085357737-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7xzJyi9JVzRwnV6JzUho%2Fuploads%2Fgit-blob-9a4344f5a9264459aa6126c25d7c5a27656ac44b%2Froles.png?alt=media) **1** How many roles exist. Three ship with the product and cannot be edited or deleted: | Role | What it is for | Main permissions | | --------------- | -------------------------- | --------------------------------------------------------------------------------------------- | | **Org Admin** | Organization administrator | Full management of users, assets, accounts, permissions, and settings inside the organization | | **Org Auditor** | Organization auditor | Viewing logs, sessions, recordings, and audit reports of the organization | | **Org User** | Regular user | Access to the workbench, connecting to authorized assets, and the web terminal | ## Permission modules A custom organization role is built by granting permissions per module: | Module | Typical permissions | | ------------------------ | -------------------------------------------------------------------- | | Console (Assets) | View, create, edit, and delete the organization's assets and folders | | Console (Users) | View, create, and edit the organization's users and groups | | Console (Accounts) | View and manage the accounts of the organization's assets | | Console (Authorizations) | Create and edit authorization rules | | Audit | View the organization's logs, sessions, and recordings | | Workbench (Jobs) | Run and manage tasks in the organization | ## Steps — creating a custom role 1. Open **Users › Profiles › Organization roles**. 2. Click **Create**, and set the **name** and a **comment** describing what the role is for. Write the comment — six months from now it is the only record of the intent. 3. Save, then open the role's details page. 4. Under **Role information › Permissions**, tick the permissions for each module. 5. Click **Submit**. ## Assigning a role Two ways, and they produce the same result: * **From the user** — edit the user and set the **Organization role** field * **From the role** — open the role's details and, under **Authorized users**, click **Add** ## How to verify it worked 1. Sign in as a user holding the role, or ask them to. 2. Confirm the console shows exactly the areas the role grants, and no others. 3. Confirm they *cannot* reach a screen the role does not grant. Testing only what should work leaves the over-permission undetected, and over-permission is the failure that matters here. ## Field reference | Field | What it means | | --------------------------- | ------------------------------------------------------------------------------ | | Name | The role's name inside the organization | | Number of users | How many users hold it | | Built-in | Whether it ships with the product and cannot be edited or deleted | | Comment | Free text describing the role's purpose | | Scope | The context the role applies to. For organization roles, always *Organization* | | ID | Internal identifier | | Date created / Date updated | Creation and last change | | Creator / Last updater | Who created it and who last changed it | ## Related pages * [Users and groups](/pam/administration/identities/users-and-groups) * [Authorizations](/pam/administration/access/authorizations) — which assets, rather than which screens * [Audit trail](/pam/administration/audit/audit-trail) # LDAP and Active Directory Authenticate console users against an LDAP or Active Directory server and provision their user records from directory attributes, including the group membership that drives authorizations. ## What this is and when to use it Connecting a directory does two things at once: people sign in to the solution with the credentials they already have, and their user record is created here from directory attributes instead of being typed by hand. Group membership comes across with them, which is what makes authorizations maintainable — you add someone to a group in Active Directory and their access here follows, and take them out of it and the access follows too. Use it whenever the organization already has a directory. Keep a small number of local accounts as well, for emergencies and for local administration, since a directory outage otherwise locks everyone out. {% hint style="warning" %} Three different features touch Active Directory, and they are routinely confused: * **This page** — the directory authenticates *console users* and supplies their attributes. Nothing is installed anywhere. * **Account discovery and rotation** — directory accounts treated as *managed credentials* the solution stores and rotates. That runs over WinRM or OpenSSH against the domain, not over this LDAP connection. See [Discovery of accounts](/pam/administration/accounts/discovery-of-accounts). * **AD Bridge** — joining *Linux servers* to the domain so directory identities become operating-system accounts on the host. That is a property of the target, not of console login. {% endhint %} ## Before you start * The **SYSADMIN** profile. * Reachability from the solution to the directory, and the service account it will bind with. * If you intend to use LDAPS, the certificate files, and a maintenance window — the service has to be restarted (see below). * A decision on scope: which part of the directory you actually want here. {% hint style="info" %} During a pilot, do not point the solution at the whole domain. Bring across only the users and accounts you intend to work with. Reducing scope later is much more work than widening it. {% endhint %} ## Steps 1. Open **System Settings › Authentication › LDAP** and enable the provider. Only enabled providers appear on the login screen. 2. Fill in the directory connection parameters and the bind account for your server, and the part of the tree to search. 3. Set the **User attribute** map — the JSON that says which directory attribute feeds which field here. This is the field that decides whether imported users are usable; see [Attribute mapping](#attribute-mapping). 4. Set the **Organization** that directory users are created in, if user creation is enabled. This determines the tenant they land in. 5. For high availability, configure **LDAP HA** with the fallback server. It is used when the primary does not answer. 6. Save, then read the two warnings below before you consider the job done. ### Attribute mapping The map is plain JSON. A full Active Directory mapping, including groups: ```json { "username": "samAccountName", "name": "displayName", "email": "mail", "groups": "memberof" } ``` Omit `groups` and only the users are imported, not the groups they belong to: ```json { "name": "cn", "email": "mail", "username": "sAMAccountName" } ``` That second form is deliberate, and it is a common choice: membership of one directory group (say `XPTO`) is what qualifies a person to reach the solution at all, while the access they get once inside is granted entirely here. You get the directory logins without importing the directory's group structure. ### Periodic synchronisation The import can run on a schedule, so that group membership in the console keeps following the directory instead of reflecting the day someone was first imported. | Field | What it does | | -------------------- | -------------------------------------------------------------- | | Periodic import | Turns the scheduled import on | | Interval, or Crontab | How often it runs. A crontab expression wins over the interval | | Organisations | Which organisations imported users land in | | Recipients | Who receives the result of each run by e-mail | **Group membership is synchronised in both directions.** On each run, the import compares the directory groups a user belongs to now against the groups they hold here, and removes them from the ones they have left. Move someone out of a group in Active Directory and the next run takes them out of the matching group in the console, and with it the access that group carried. {% hint style="warning" %} **Only groups that came from the directory are touched.** The comparison is limited to groups whose name carries the `AD` prefix the import gives them. Groups you create by hand here are never modified by a directory run, which is what you want: local grouping survives, directory grouping follows the directory. **Leaving the directory is not the same as leaving a group.** Removal from a group is applied on the next run. A user account deleted or disabled in the directory is a different case: the account here is not deactivated by the import, so treat directory offboarding as a separate step. This is also why public-key authentication has to be off, as the warning above explains. {% endhint %} ### LDAPS To use LDAP over TLS, load `ldap_ca.pem`, `ldap_cert.pem`, and `ldap_cert.key` onto the appliance and restart the service. The certificates are not uploaded through this screen, and the new files are not picked up until the restart. {% hint style="danger" %} **Turn off public-key authentication once directory authentication is live.** In **System Settings › Components › SSH & Terminal Protocol**, **Public key** is enabled by default. If you leave it on, a user who has been removed from Active Directory can still reach assets with an SSH key they registered earlier — their directory account is gone, and the offboarding is silently incomplete. Disable it so every terminal session is authenticated through the directory. {% endhint %} ## What you should see The login screen offers the directory as a sign-in option. Nothing else on the settings screen tells you the connection is healthy. ## How to verify it worked 1. Sign in as a directory user who is not already a local user here. 2. Open **Users › Users** and find them. The **Source** column must read `LDAP/AD`, not `Local`. If it reads `Local`, you authenticated against a pre-existing local account and have proved nothing. 3. Check that **Name** and **Email** are populated. Blank fields mean the attribute map is wrong, even though the login succeeded. 4. If you mapped `groups`, confirm the user's **User groups** reflect their directory membership. 5. Check the login appears in the audit trail with the directory as the authentication source. See [Audit trail](/pam/administration/audit/audit-trail). The login succeeding on its own is not enough of a check: the common failure is a successful login that produces an unusable user record. ## Common errors | Symptom | Cause | Fix | | ------------------------------------------------------ | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | Directory users log in but have no name or email | The **User attribute** map names attributes the directory does not publish | Correct the JSON — `samAccountName`, `displayName`, `mail` for Active Directory | | Users import but belong to no groups | `groups` is absent from the map | Add `"groups": "memberof"`, or grant access through groups defined here instead | | LDAPS fails after loading the certificates | The service was not restarted | Restart the service; the files are read at start-up | | A user removed from the directory still reaches assets | **Public key** authentication is still enabled on the terminal connector | Disable it in **System Settings › Components › SSH & Terminal Protocol** | | A directory user reappears after being deleted here | The directory is the source of the record | Remove or disable the account at the directory, not here | | Nobody can sign in during a directory outage | Every account is directory-backed | Keep at least one local emergency account | ## Field reference | Field | What it means | | -------------------- | -------------------------------------------------------------------------------- | | Enable | Per-provider checkbox. Only enabled providers appear on the login screen | | User attribute | JSON map from directory attributes to `username`, `name`, `email`, and `groups` | | Organization | The tenant that directory users are created in when user creation is enabled | | LDAP HA | A second, high-availability directory server used as fallback | | Periodic import | Runs the import on a schedule, which is what keeps group membership current | | Interval, or Crontab | How often the scheduled import runs. A crontab expression wins over the interval | | Recipients | Who receives the outcome of each scheduled run by e-mail | Mapping keys, and their usual Active Directory sources: | Key | Directory attribute | Notes | | ---------- | ---------------------- | --------------------------------------------------- | | `username` | `sAMAccountName` | The login. Must be unique | | `name` | `displayName`, or `cn` | Display name | | `email` | `mail` | Notifications and password recovery | | `groups` | `memberof` | Optional. Omit to import users without their groups | Radius is configured alongside the directory providers, but it is an external authentication server rather than a directory — it is most often used to add a one-time-password factor. See [Multi-factor authentication](/pam/administration/identities/mfa). ## Related pages * [Users and groups](/pam/administration/identities/users-and-groups) — the user records this creates * [Single sign-on](/pam/administration/identities/sso) — the federated methods: SAML2, OIDC, OAuth2, CAS * [Multi-factor authentication](/pam/administration/identities/mfa) — adding a second factor on top * [Authorizations](/pam/administration/access/authorizations) — what an imported group can reach * [Discovery of accounts](/pam/administration/accounts/discovery-of-accounts) — directory accounts as managed credentials # Single sign-on Delegate console login to a corporate identity provider over SAML2, OIDC, OAuth2, CAS, or Slack, and map the provider's attributes onto user records here. ## What this is and when to use it With single sign-on, the identity provider authenticates the person and the solution trusts the assertion it gets back. Users reach the console without a separate password, and the second factor and conditional-access rules configured in the corporate provider are honoured at this login too. Use it when the organization already runs an identity provider — Entra ID (Azure AD)/ADFS, Okta, Keycloak, PingFederate, OneLogin, Google Workspace. If what you have is a directory rather than a federation provider, see [LDAP and Active Directory](/pam/administration/identities/ldap-and-ad) instead. {% hint style="warning" %} The solution acts **exclusively as a Service Provider**. It consumes assertions from an identity provider; it cannot act as an identity provider for other applications. {% endhint %} Methods can be enabled individually and coexist, so a migration does not have to be a cutover — leave local login and the old method enabled until the new one is proved. ## Which method to pick | Method | Use it for | | ---------- | ----------------------------------------------------------------------------- | | **SAML2** | The enterprise default. Entra ID/ADFS, Okta, PingFederate, OneLogin | | **OIDC** | Modern SSO on top of OAuth 2.0. Keycloak, Entra ID, Google Workspace, Okta | | **OAuth2** | A provider with no OIDC or SAML support, where you wire the endpoints by hand | | **CAS** | An existing CAS deployment. Ticket-based; version 3 is supported | | **Slack** | Teams that already live in Slack. Needs a Slack App | ## Before you start * The **SYSADMIN** profile. * Administrative access to the identity provider, or someone who has it — the configuration is symmetric and both halves must be done. * The public URL of this installation. The callback URL the provider redirects to is derived from it, and a mismatch is the usual first failure. * For SAML2, the Service Provider certificate to upload, and the identity provider's metadata. * For OAuth2, the authorization, token, and userinfo endpoints. * For Slack, a Slack App with its Client ID and Client Secret. ## Steps 1. Open **System Settings › Authentication** and select the method. 2. Enable the provider. Only enabled providers appear on the login screen. 3. Enter the provider-specific configuration: * **SAML2** — upload the SP certificate and configure the IdP side. * **OIDC** — the provider details, plus the **Realm** for Keycloak and the shared-session setting. * **OAuth2** — the authorization, token, and userinfo endpoints, configured manually. * **CAS** — the CAS server, using the URLs below. * **Slack** — the Slack App's Client ID and Client Secret. 4. Set the **User attribute** map — the JSON that says which claim or attribute from the provider feeds `username`, `name`, and `email` here. See [Attribute mapping](#attribute-mapping). 5. Set the **Organization** that provider users are created in, if user creation is enabled. This decides which tenant they land in. 6. Register the callback URL on the provider side, exactly as the solution publishes it. 7. Save, and test in a private browser window so you do not lose your current session. ### Service URLs Each provider exposes three endpoints under the installation's own hostname: | Purpose | Path | | ------------------------- | ------------------------------------------------------ | | Login | `https:///core/auth//login/` | | Successful-login callback | `https:///core/auth//callback/` | | Logout | `https:///core/auth//logout/` | `` is the method's own name — `cas`, `oauth2`, and so on. The callback URL is the one that has to be registered with the identity provider. ### Attribute mapping The map is plain JSON, and the keys on the right are whatever the provider calls its attributes. CAS publishes prefixed attribute names: ```json { "cas:user": "username", "cas:fullname": "name", "cas:mail": "email" } ``` An OAuth2 provider that exposes a scoped email claim: ```json { "name": "user", "username": "name", "email": "user:email" } ``` Take the attribute names from the provider's own documentation or from a test assertion. Guessing produces a successful login and a user record with blank fields. ## What you should see The login screen gains a button for the provider. Local login stays available unless you disable it. ## How to verify it worked 1. In a private browser window, open the console and choose the provider. You should be redirected to the identity provider, authenticate there, and return signed in. 2. Open **Users › Users** and find the user. The **Source** column must show the external provider rather than `Local` — otherwise you signed in against a pre-existing local account and have tested nothing. 3. Check **Name** and **Email** on that record. Blank fields mean the attribute map is wrong even though the login worked. 4. Confirm the user landed in the intended organization. 5. Check the sign-in is recorded in the audit trail with the provider as the authentication source. See [Audit trail](/pam/administration/audit/audit-trail). 6. Sign out and confirm you are not silently signed straight back in — the logout URL is part of the configuration for a reason. ## Common errors | Symptom | Cause | Fix | | ------------------------------------------------ | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | The provider is missing from the login screen | It is configured but not enabled | Tick the provider's enable checkbox | | The identity provider refuses the redirect | The callback URL registered there does not match the one published here | Register the exact `/core/auth//callback/` URL, including scheme and hostname | | Login succeeds but the user has no name or email | The **User attribute** map names claims the provider does not send | Correct the JSON against a real assertion from the provider | | Users appear in the wrong tenant | **Organization** on the provider is not the one you expected | Set it before the first sign-in; moving users afterwards is manual | | You are locked out mid-configuration | The only enabled method is the one being changed | Keep local login enabled until SSO is proved, and test in a private window | | Sign-out returns you straight to the console | The provider's session is still open | Configure the logout URL so the session is ended at the provider too | ## Field reference Fields common to every provider: | Field | What it means | | -------------- | --------------------------------------------------------------------------- | | Enable | Per-provider checkbox. Only enabled providers appear on the login screen | | User attribute | JSON map from the provider's attributes to `username`, `name`, and `email` | | Organization | The tenant that provider users are created in when user creation is enabled | Provider-specific configuration documented for each method: | Method | Configuration | | ------ | ---------------------------------------------------------------------- | | SAML2 | Upload of the Service Provider certificate, plus the IdP configuration | | OIDC | Provider details, **Realm** (for Keycloak), and shared-session control | | OAuth2 | Authorization, token, and userinfo endpoints, entered manually | | CAS | CAS server, with login, callback, and logout URLs. Supports version 3 | | Slack | A Slack App's Client ID and Client Secret | ## Related pages * [LDAP and Active Directory](/pam/administration/identities/ldap-and-ad) — directory login and user sync * [Multi-factor authentication](/pam/administration/identities/mfa) — a second factor here, or delegated to the identity provider * [Users and groups](/pam/administration/identities/users-and-groups) — the records SSO creates * [Login policies](/pam/administration/access/login-policies) — when and from where sign-in is allowed * [Roles and permissions](/pam/administration/identities/roles) — what a user may do once inside # Multi-factor authentication Require a second authentication factor for console access — globally, or per user — how a user enrols an authenticator app, and how to reset a factor someone has lost. ## What this is and when to use it Multi-factor authentication adds a factor on top of the username and password so that a stolen or guessed password is not, by itself, enough to sign in. It sits on top of whichever authentication method the user arrives by — local password, a directory, or a federated provider — rather than replacing any of them. Turn it on for everyone. In a privileged access solution, an operator's console account is the key to every managed credential in the environment, and the password to it is the weakest thing protecting them. {% hint style="danger" %} Enable MFA for all users. Everything else on this page is detail; this is the setting that matters. {% endhint %} Some operations in the console require MFA on the operator's *own* account and are simply unavailable without it — revealing a stored secret, and exporting accounts. See [Account templates](/pam/administration/accounts/account-templates) and [Vault](/pam/administration/accounts/vault). ## Available factors | Factor | What it is | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **OTP / TOTP** | A rotating code on the OATH-TOTP standard, compatible with any authenticator app — Google Authenticator, Microsoft Authenticator, FreeOTP, Authy | | **SMS** | A verification code by text message. Requires a configured SMS provider | | **Email** | A verification code by email | | **Radius** | A token or one-time password validated by a Radius server — RSA SecurID, Duo Security, Microsoft NPS | | **Passkey / FIDO2** | A phishing-resistant key: a hardware security key such as a YubiKey, or device biometrics. Must be enabled in **System Settings › Authentication** | | **Digital certificate / smartcard** | A client certificate on a smartcard or cryptographic token, or the equivalent delegated to a federated provider | | **Delegated to the identity provider** | When the solution is federated over SAML2 or OIDC, the second factor and conditional-access policies configured in Entra ID/ADFS, Okta, or Keycloak are honoured at this login | {% hint style="info" %} OTP/TOTP is the right default for most deployments. It works offline, it does not depend on message delivery, and it needs no hardware beyond a phone. {% endhint %} ## Before you start * The **SYSADMIN** profile for the global setting. * An accurate clock on the server. TOTP is second-precision, and clock drift breaks every code at once — see [Common errors](#common-errors). * A configured provider first, if you intend to use SMS or email as a factor. * Passkey enabled in **System Settings › Authentication**, if you intend to use it. ## Steps ### Require it globally 1. Open **System Settings › Security › Authentication › Global MFA**. 2. Choose the scope: | Option | Effect | | ------------------- | -------------------------------------------------- | | Disabled | Users authenticate with username and password only | | All users | MFA is required for every user | | Administrators only | MFA is required only for administrative users | 3. Save. {% hint style="warning" %} Once **All users** is set, individual users can no longer turn MFA off for themselves. That is the intent — but it also means the setting is the only place the requirement can be relaxed, so plan for enrolment before you flip it. {% endhint %} ### Require it for one user The user record carries its own MFA setting, in **Users › Users**. Use it for the exceptions: a specific administrator or a contractor who needs the factor while the global setting is still `Disabled` or `Administrators only`. ### How a user enrols The user does this themselves; an administrator cannot enrol on their behalf. 1. In **Personal Settings**, the user starts OTP registration. 2. The console shows a QR code carrying the TOTP secret. 3. The user scans it with their authenticator app. 4. From then on, the app generates the six-digit code the login asks for. ### Reset a lost factor If someone loses their phone or security key, an administrator clears the enrolment so they can register again. 1. Open **Users › Users** and click the username to open the user's detail page. 2. In the quick-update panel at the top right, click **Reset MFA**. The user is prompted to enrol again at their next sign-in. {% hint style="warning" %} **You cannot reset your own MFA this way.** Signed in as an administrator, the Reset MFA action on your own record does not apply — so if the account with the highest privilege loses its factor, there is no self-service route back. Make sure at least one other account holds enough privilege to reset yours. {% endhint %} ## What you should see After enabling **Global MFA**, the login screen asks for the code as a second step, after the password has been accepted. Users who have not enrolled are taken through enrolment. ## How to verify it worked 1. In a private browser window, sign in as an affected user. The password alone must not get you in; you should be asked for a code, or taken through enrolment. 2. Open that user's record in **Users › Users** and confirm **MFA** is on and **MFA virtual bound** shows a linked authenticator. 3. As that user, try to switch MFA off in **Personal Settings**. Under **All users** the option must not be available. If it is, the global setting did not take. 4. Check that the login, and any failed second-factor attempt, is recorded in the audit trail. See [Audit trail](/pam/administration/audit/audit-trail). 5. As an operator with MFA now enabled, reveal an account secret. It should work where it previously did not. ## Common errors | Symptom | Cause | Fix | | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | `OTP code invalid, or server time error`, for every user at once | The server clock has drifted. TOTP is second-precision | Correct the time on the server and keep it synchronised; a working NTP source is a prerequisite, not an optimisation | | One user's codes are always rejected | The clock on that user's device has drifted, or they are reading a stale enrolment | Correct the device clock, or reset MFA and re-enrol | | A user lost their phone and cannot sign in | The factor is bound to the lost device | An administrator resets MFA on the user's record; the user re-enrols at next login | | An administrator cannot reset their own MFA | By design — the action does not apply to your own account | Have another privileged account perform the reset | | A stored secret cannot be revealed, or **Export** is greyed out | MFA is not enabled on the *operator's* account | Enable MFA on your own account, then retry. See [Vault](/pam/administration/accounts/vault) | | A user can still turn MFA off | **Global MFA** is `Disabled` or `Administrators only` and they are not an administrator | Set it to **All users** | | SMS or email codes never arrive | No provider is configured for that channel | Configure the provider, or use OTP/TOTP, which needs no delivery channel | ## Field reference ### Global MFA | Value | Effect | | ------------------- | ------------------------------------------------------ | | Disabled | Username and password only | | All users | Required for everyone; individual users cannot opt out | | Administrators only | Required for administrative users | ### On the user record | Field | What it means | | ----------------- | --------------------------------------------------------------------------------------------------------------------- | | MFA | Whether a second factor is required for this user | | MFA virtual bound | Whether an authenticator app or device is actually linked. Required *and* unbound means the user has not enrolled yet | In the bulk user-import template, **MFA** is written in `name(value)` form — for example `Disabled(0)` or `Enabled(1)`. The template accepts the values `0`, `1`, and `2`. ### Adjacent settings on the same screen **System Settings › Security › Authentication** also carries login controls that are not MFA but are often configured in the same pass: | Setting | What it does | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | Login captcha | Requires a captcha at login, to block automated sign-in attempts | | Login dynamic code | Sends the password and an additional code to a third-party authentication system for verification | | Auto disable threshold (day) | Detects accounts that have not been used within the given number of days and disables them | | Suspicious login verification | Checks whether the login IP belongs to a city the account usually signs in from, and sends the user a remote-login notice when it does not | Detection of genuinely anomalous access — unusual hours, a new location, improbable travel — and the automatic response to it belong to the behavioural analytics module rather than to these checks. See [UEBA policy](/pam/administration/ueba/policy). ## Related pages * [Users and groups](/pam/administration/identities/users-and-groups) — where the per-user MFA setting lives * [Single sign-on](/pam/administration/identities/sso) — delegating the second factor to a corporate provider * [Login policies](/pam/administration/access/login-policies) — when and from where sign-in is allowed at all * [Vault](/pam/administration/accounts/vault) — secret reveal, which requires MFA * [Account templates](/pam/administration/accounts/account-templates) — account export, which requires MFA # Connectivity | Page | What it covers | | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [Proxy](/pam/administration/connectivity/proxy) | Reach assets through an intermediate jump machine when the solution has a route into the network but not to the assets themselves. | | [Gateways](/pam/administration/connectivity/gateways) | Jump hosts registered inside a proxy, and how the network devices and out-of-band consoles usually reached through them are discovered, mediated and audited. | | [Broker](/pam/administration/connectivity/broker) | Zero-trust reverse connectivity: the remote gateway and the solution both dial out to a broker, so assets in networks that cannot accept inbound connections stay reachable without a VPN. | | [Connectors](/pam/administration/connectivity/connectors) | An agent installed on the target machine itself, which dials out to a broker and makes a solitary host reachable when there is no gateway on its network. | | [Endpoints](/pam/administration/connectivity/endpoints) | The address and port the console hands to a client when a session opens, and why changing a port here does not move the service that is actually listening. | # Proxy Reach assets through an intermediate jump machine when the solution has a route into the network but not to the assets themselves. A **Proxy** is the record that describes an intermediate machine the solution uses as a jump point. Instead of connecting to the asset, the solution connects to the proxy and, from inside it, reaches the final destination. The screen states the purpose directly: *"Reach assets through a gateway when the network isn't directly accessible"*. ## What this is and when to use it The connection **leaves the solution and travels toward the asset network**. The solution opens a session on the proxy using an account registered on it and forwards the traffic to the asset through that session. That has one consequence worth stating up front: **the solution must be able to reach the proxy over the network**. Use a proxy when there is a route to one machine in the target network but not to the assets themselves — a segmented subnet where only one server is reachable, or an environment where only one host has the port opened on the firewall. {% hint style="info" %} **Proxy and gateway are two halves of the same mechanism, not two mechanisms.** The proxy is the record you attach assets to; the jump machines themselves are gateways registered inside it, on the proxy's **Gateways** tab. The console does not offer a separate "proxy engine" you configure elsewhere. See [Gateways](/pam/administration/connectivity/gateways) for the jump machines. {% endhint %} A proxy corresponds to a **zone** — the place where the assets live, such as a data centre, a public cloud, or a VPC. Gateways are configured inside the zone, and users log in to the assets through them when the network cannot be reached directly. ### Proxy or broker | Situation | Mechanism | | ----------------------------------------------------------------------------------- | ---------- | | The solution reaches a machine in the network, but not the assets | **Proxy** | | The solution cannot reach the network at all, and you will not open an inbound port | **Broker** | {% hint style="warning" %} An asset uses **either a proxy or a broker gateway, never both**. They are alternative paths to the same goal, and the asset registration form makes you choose one. {% endhint %} ## Before you start * A network route from the solution to the proxy machine, with the port opened in the solution-to-proxy direction. * An **account with a credential** registered on the proxy machine — the jump is performed with it. * The proxy machine must be able to see the assets it will serve. * The platform of each target asset must allow proxied connections. On [Platforms](/pam/administration/assets/platforms), the **Gateway enabled** switch in **Quick update** controls whether connections to that platform may pass through a gateway. ## Steps 1. In **Console › Gateway › Proxy**, use **Create** and give the proxy a name and a description that identifies the network it represents. 2. On the proxy's **Gateways** tab, associate the jump machines that belong to it. Registering those machines is covered in [Gateways](/pam/administration/connectivity/gateways). 3. Attach the assets that will be reached through this proxy. The proxy's **Assets** tab shows everything currently bound to it. 4. Grant the usual access authorization to the users who need those assets — a proxied asset is authorized like any other. Existing proxies can be imported from a file with **Upload**, and the list can be exported with **Export**. ## What you should see ![The Proxy screen, listing the zones](https://1085357737-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7xzJyi9JVzRwnV6JzUho%2Fuploads%2Fgit-blob-f25dd8678e79558eb105e33599368e523f7659aa%2Fproxy.png?alt=media) **1** How many zones exist. The list shows the registered proxies with a total at the top. Selecting an item opens the detail panel on the right, with three tabs: | Tab | Content | | ------------ | ------------------------------- | | **Detail** | Registration data for the proxy | | **Gateways** | Associated jump machines | | **Assets** | Assets that use this proxy | The **Detail** tab shows **Name**, **Devices** (how many devices are served), **Gateway**, **Date created**, **Update date** and **Description**. ## How to verify it worked Nothing on the Proxy screen proves that the jump itself works — the list will show a proxy with a gateway attached whether or not traffic can actually flow. Verify against an asset instead: 1. Open the asset in [Inventory](/pam/administration/assets/inventory) and run **Test connectivity** from its **Quick update** block. Success means the solution reached the asset through the jump path. 2. Start a real session with one of the [connection methods](/pam/administration/sessions/connection-methods). The session opens and is recorded exactly as a direct session would be. 3. Back on the proxy's **Detail** tab, the **Devices** count and the **Assets** tab should list the assets you attached. ## Common errors | Symptom | Cause | Fix | | ------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | | Sessions to the assets fail, though the proxy record looks complete | The solution has no route or no open port to the proxy machine | Open the path in the solution-to-proxy direction; the connection is always outbound from the solution | | The session fails while authenticating on the jump machine | The proxy has no account with a credential, or the credential is wrong | Register an account with a working credential on the proxy machine — the jump is made with it | | The connection ignores the proxy and goes straight to the asset | The asset's platform does not allow proxied connections | Turn on **Gateway enabled** for that platform | | The asset registration will not accept both paths | An asset may use a proxy or a broker gateway, not both | Decide which path that asset uses and clear the other | | The proxy is reachable but only some assets work | The jump machine cannot see the remaining assets from its own network position | Check reachability from the jump machine to each asset, not from the solution | ## Field reference ### Toolbar | Control | What it does | | ----------------------- | -------------------------------------------- | | **Create** | Registers a new proxy | | **Upload** | Imports proxies from a file | | **Export** | Exports the list | | **Search**, **Refresh** | Finds and reloads entries | | Sorting and columns | Change the order and which columns are shown | ### Optional list columns The column selector turns these on and off: **Assets**, **Description**, **Gateway** and **Tags**. **Name** and **Actions** are always shown and cannot be hidden. ## Related pages * [Gateways](/pam/administration/connectivity/gateways) — the jump machines registered inside a proxy * [Broker](/pam/administration/connectivity/broker) — the reverse path, for networks the solution cannot reach * [Platforms](/pam/administration/assets/platforms) — where **Gateway enabled** is set * [Inventory](/pam/administration/assets/inventory) — attaching assets and testing connectivity * [Connection methods](/pam/administration/sessions/connection-methods) — how users open the session # Gateways Jump hosts registered inside a proxy, and how the network devices and out-of-band consoles usually reached through them are discovered, mediated and audited. A **gateway** is a jump host: a machine inside the asset network that the solution logs in to and forwards traffic through, so that assets with no direct route can still be reached. Gateways are not standalone records — each one belongs to a [Proxy](/pam/administration/connectivity/proxy), which is the zone the assets are attached to. {% hint style="warning" %} **Two different things are called "gateway".** This page is about the jump host inside a network the solution can reach, where the solution dials **in**. The other one is the appliance installed at a remote site that dials **out** to a [Broker](/pam/administration/connectivity/broker), used when the solution cannot reach the network at all. They are not interchangeable, and an asset uses one path or the other, never both. {% endhint %} ## What this is and when to use it Use a gateway when only one machine of a network is reachable — a segmented subnet with a single exposed server, a management VLAN, or an environment where the firewall opens one host only. Everything behind it is then reached through that single hop, with the session mediated, recorded and audited exactly as a direct session would be. Management networks are the usual case, which is why this page also covers the device classes most often found behind a jump host: switches, routers, firewalls, load balancers, access points, biometric readers, VoIP equipment, storage controllers and out-of-band consoles. ## Before you start * The jump host must be registered as an asset. The **Gateway** platform exists for exactly this: it has the same protocol set as **Linux** (SSH 22, SFTP 22, Telnet 23, VNC 5900, RDP 3389) and is kept separate only to make the host's role obvious in the inventory. * The jump host needs an account with a working credential — the hop is made with it. * A [Proxy](/pam/administration/connectivity/proxy) record to attach the gateway to. * On the **platform of each target asset**, **Gateway enabled** must be on, or connections to that platform will not use the jump path. ## Steps 1. Register the jump host in [Inventory](/pam/administration/assets/inventory) on the **Gateway** platform, with the address the solution can reach, and add an account with its credential. 2. In **Console › Gateway › Proxy**, open the proxy that represents the network and associate the jump host on its **Gateways** tab. 3. Attach the assets that will be reached through it, and confirm their platforms have **Gateway enabled**. 4. Grant the access authorization to the users or groups who need those assets. ## Network devices and out-of-band consoles Privileged access is not limited to servers and databases. Network, storage and remote-management equipment is managed as ordinary assets, grouped by type, location and criticality. {% hint style="info" %} Network and OOB equipment shares the governance model of every other asset: the privileged credential lives in the vault, the access is mediated, and the session is recorded and auditable. {% endhint %} ### Discovery Discovery maps the equipment that uses privileged credentials by scanning subnets, IP lists or CIDR ranges and identifying devices through their management protocols. | Protocol | What it is used for | | ------------------- | --------------------------------------------------------------------------------------------------- | | **SSH** | Finds hosts with an active SSH service; collects the banner and the host key fingerprint | | **Telnet** | Identifies legacy equipment that still exposes a CLI over Telnet | | **HTTPS / web GUI** | Detects web administration interfaces — firewall panels, storage controllers, management consoles | | **SNMP** | Reads `sysDescr`, `sysObjectID` and other standard OIDs to classify vendor, model and role | | **CLI** | Recognizes the prompt type and network operating system, so the command parser matches the platform | Two modes are available: * **Scheduled** — you define the ranges, the read credentials and a scan window; the inventory is refreshed periodically and new, changed or disappeared assets are flagged. * **On demand** — you scan a specific range and review the candidates before promoting them to managed assets, deciding which credentials get imported into the vault. {% hint style="warning" %} Use **read-only credentials** during discovery — an SNMP `read-only` community or a dedicated inventory user. Promote a device to full privileged access only after it has been classified. {% endhint %} ### Vendors and equipment Connection profiles and command parsers are pre-configured for the common vendors; anything else is accommodated through generic SSH, Telnet or HTTPS profiles. | Vendor | Equipment types | Typical protocols | | ------------- | ---------------------------------------------------------------------------------- | ------------------------------ | | **Cisco** | Switches, routers, firewalls (ASA/Firepower) | SSH, Telnet, HTTPS, SNMP | | **Dell** | Switches, storage, iDRAC consoles | SSH, HTTPS, SNMP, IPMI | | **HPE** | Switches (Aruba), storage, iLO consoles | SSH, HTTPS, SNMP, IPMI | | **Fortinet** | Firewalls (FortiGate), switches | SSH, HTTPS, SNMP | | **Palo Alto** | Next-generation firewalls | SSH, HTTPS (web GUI), SNMP | | **Huawei** | Switches, routers, storage | SSH, Telnet, HTTPS, SNMP | | **Juniper** | Switches, routers, firewalls (SRX) | SSH, HTTPS, SNMP | | **Lenovo** | Servers, switches, XClarity Controller (XCC) consoles | SSH, HTTPS, SNMP, IPMI/Redfish | | **Others** | Load balancers, storage controllers and anything compatible with a generic profile | SSH, Telnet, HTTPS, SNMP, CLI | {% hint style="info" %} Each vendor profile carries the right CLI prompt configuration, the privilege escalation sequence (for example, `enable` mode) and the command dictionary. That is what makes command auditing and command blocking work correctly on each platform. The **Device** category of [Platforms](/pam/administration/assets/platforms) ships **General**, **Cisco**, **Huawei**, **H3C** and **Fortinet** natively, all on SSH 22 and Telnet 23; other vendors are handled with a generic or custom platform. {% endhint %} ### Out-of-band consoles Out-of-band consoles administer a server even when its operating system is unavailable, at firmware and hardware level. | Technology | Vendor / standard | Access | | ----------------------------- | ----------------------------------------- | ---------------------------------- | | **DRAC / iDRAC** | Dell | HTTPS (web GUI), SSH, IPMI | | **iLO** | HPE | HTTPS (web GUI), SSH, IPMI | | **IPMI** | Open multi-vendor standard | IPMI over LAN, SSH | | **BMC** | Baseboard Management Controller (generic) | HTTPS, SSH, IPMI/Redfish | | **XClarity Controller (XCC)** | Lenovo | HTTPS (web GUI), SSH, IPMI/Redfish | For these consoles the solution keeps the administrative credential (`root`, `Administrator`, `admin`) in the vault so operators never learn it, mediates the HTTPS, SSH or IPMI session without revealing the password, and records the session — including the video of the console's web interface and the commands typed in the CLI. {% hint style="danger" %} An OOB console grants power equivalent to physical access to the equipment: power cycling, mounting virtual media, resetting firmware. Restrict these assets to the most trusted profiles and require approval for check-out wherever you can. {% endhint %} ### Command auditing and blocking In command-line sessions every command sent to the equipment is inspected in real time. A sensitive command can be **blocked**, **blocked with an alert**, or merely **recorded for review**, and the forbidden-command lists can be specific to a vendor or platform. Commonly blocked examples: | Command (example) | Risk | Typical action | | --------------------------------- | ----------------------------------------------- | ---------------- | | `erase startup-config` | Loss of configuration | Block | | `reload` / `reboot` | Equipment outage | Block with alert | | `delete` on storage volumes | Data loss | Block | | `username ... privilege 15` | Privileged account created outside the solution | Block with alert | | `factory-reset` on an OOB console | Hardware or firmware reset | Block | {% hint style="warning" %} Review the blocking lists periodically with the network and security teams. A list that is too broad stops legitimate maintenance; one that is too narrow leaves the destructive commands available. {% endhint %} Access to these devices can also be restricted by combining dimensions — user profile, equipment type, time window and connection origin (IP ranges, trusted networks, administration segments). The rules combine, so a policy such as "junior network operators reach the site switches only during business hours and only from the administration network" is expressible as one rule set. ## How to verify it worked 1. Run **Test connectivity** on an asset that sits behind the gateway, from its **Quick update** block in [Inventory](/pam/administration/assets/inventory). This exercises the jump path, not the gateway record. 2. Open a real session — for a network device, an [SSH session](/pam/administration/sessions/ssh) — and confirm it connects and that recording starts. 3. Check the command log for that session. Sessions are indexed by equipment, user, date and command, so an audit question such as "who ran `reload` on this router last week?" is answered from the index rather than by watching recordings. 4. After a discovery run, confirm the devices appear as candidates, classified by type, vendor, location and available protocols, before you promote them. ## Common errors | Symptom | Cause | Fix | | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | Sessions to assets behind the jump host fail | The solution has no route or no open port to the jump host itself | Open the path from the solution to the jump host; the solution always dials in on this path | | Connections bypass the jump host | The target asset's platform has **Gateway enabled** off | Turn it on for that platform | | The jump succeeds but the asset is unreachable | The jump host cannot see that asset from its own network position | Test reachability from the jump host, not from the solution | | Command blocking or command auditing behaves oddly on a device | The asset is on a generic platform whose prompt and command dictionary do not match the vendor | Move the asset to the vendor platform, or duplicate a native one and adjust it | | Discovery returns devices but no usable inventory data | The scan credentials cannot read the management protocols | Provide read-only SSH or SNMP credentials for the ranges being scanned | | An asset will not accept the jump path | It is already bound to a broker gateway | An asset uses a proxy or a broker gateway, not both | ## Field reference | Item | What it is | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Gateway** platform | Linux-based platform for jump hosts, with SSH 22, SFTP 22, Telnet 23, VNC 5900 and RDP 3389. Separate from **Linux** only to make the host's role clear in the inventory | | **Gateway enabled** | Platform switch, in **Quick update**, that allows connections to that platform to pass through a gateway | | **Gateways** tab | On a proxy's detail panel: the jump machines associated with that proxy | | **Unbind gateway** | Action on a device card that removes the device's link to a *broker* gateway. Unavailable when there is no such link | ## Related pages * [Proxy](/pam/administration/connectivity/proxy) — the record a gateway belongs to and assets attach to * [Broker](/pam/administration/connectivity/broker) — the other kind of gateway, which dials out from the remote site * [Platforms](/pam/administration/assets/platforms) — the **Gateway** platform and **Gateway enabled** * [Inventory](/pam/administration/assets/inventory) — registering the jump host and testing connectivity * [SSH sessions](/pam/administration/sessions/ssh) — the usual way network devices are reached # Broker Zero-trust reverse connectivity: the remote gateway and the solution both dial out to a broker, so assets in networks that cannot accept inbound connections stay reachable without a VPN. A **broker** is the meeting point for reverse access. It is a service on a dedicated VM that acts as the control centre of a zero-trust overlay network. It sits neither inside the customer network nor inside the solution, but somewhere **both sides can reach**. The screen states the purpose directly: *"Zero-trust reverse connectivity: remote gateways and the PAM dial out to a broker. No inbound port is opened on the targets"*. ## What this is and when to use it The broker **reverses the direction of the connection**. Instead of the solution entering the customer network, the remote gateways and connectors dial out to the broker, and the solution dials out to the broker as well. The two sides meet there. ``` [target on the remote network] <--- gateway --dials--> BROKER (public) <--dials-- solution ``` Each end is authenticated by certificate, and only the assets you explicitly publish become reachable. The customer network exposes no inbound port at all. Use a broker when there is no route from the solution to the asset network and you cannot, or will not, open inbound firewall ports or build a VPN. That is the typical situation for third-party networks, branch offices, customer sites and anything behind NAT. {% hint style="info" %} **Broker gateway is not the same as a proxy gateway.** A broker gateway is an appliance installed next to the targets that only makes outbound connections. A proxy gateway is a jump host the solution dials into — see [Gateways](/pam/administration/connectivity/gateways). An asset uses one path or the other, never both. {% endhint %} | Situation | Mechanism | | ------------------------------------------------------------------------ | --------------------------------------------------------- | | The solution reaches a machine in the network, but not the assets | [Proxy](/pam/administration/connectivity/proxy) | | The solution cannot reach the network, and no inbound port may be opened | **Broker** | | The target is a single isolated machine with no gateway on its network | [Connectors](/pam/administration/connectivity/connectors) | Once the path exists, nothing else changes: the session is mediated, recorded and audited exactly like a session to a local asset, with session recording, command filtering, auditing and anomaly alerts all applying the same way. ## Before you start * Administrator (**SysAdmin**) privileges in the console. * A **broker** provisioned and reachable — a dedicated VM, delivered as part of the DataDike infrastructure. * A machine or appliance at the remote site to act as the gateway, with **outbound** internet access. It needs no public IP and no open inbound port. * The broker VM must accept inbound connections on its control port and its data port. The product notes list **1280/tcp** for control and **443/tcp** for data, while the registration form defaults to an admin port of `1280` and a router port of `3022`. Confirm which pair your broker build uses before opening the firewall. Gateway appliance requirements: | Resource | Recommended minimum | | -------- | ------------------------------------------------------------ | | System | An actively supported Linux distribution | | vCPU | 4 | | Memory | 8 GB | | Disk | 60 GB | | Network | **Outbound** internet access (no public IP, no inbound port) | {% hint style="danger" %} **Register the broker by DNS name, never by IP.** The address is written into the certificates and the enrollment tokens and **cannot be changed afterwards without reinstalling the broker**. A literal IP only ever works for one network path, because behind NAT the LAN and the internet do not see the same IP. {% endhint %} Everything is managed in **Console › Gateway › Brokers**. The only step outside the console is running the gateway installer once, at the remote site, with a token the console generates. ## Steps 1. **Register the broker.** In **Console › Gateway › Brokers**, use **Register broker** and supply the broker host, the admin port (default `1280`), the router port (default `3022`) and the broker's administration token. The token is stored masked and encrypted in the vault and is never displayed again after saving. Then run **Test connection** — the status should come back *online*, with the broker version and the active routers. 2. **Enroll the site gateway.** Open the broker and, on the **Gateways** tab, use **Enroll gateway** and name it after the site (for example, `gateway-branch-sp`). The console issues a **single-use JWT**, shown only once. Run the gateway installer on the remote machine with that token: ```bash sudo ./install-gateway.sh --token "" ``` As soon as the gateway connects to the broker it appears *online* on the **Gateways** tab. 3. **Publish the target.** On the **Targets** tab, use **Publish target** and fill in the gateway that can see the asset, the target address as `IP:port` **as reachable from the gateway** (for example, `10.0.0.5:22` for SSH or `:3389` for RDP), a unique service name, and a dedicated high local port on the solution — **12000 or above**. 4. **Register the asset.** Register the asset as usual, pointing its address at the **local port** from the previous step. Platform, accounts and credentials are configured exactly as for a local asset. 5. **Grant access and connect.** Grant the normal [authorization](/pam/administration/access/authorizations) to the user or group. The user connects from the browser with nothing to install. {% hint style="warning" %} The enrollment token is **single-use** and already embeds the broker address — the site operator never types an IP. If the token expires or is consumed without the installation completing, generate a new one from the screen. {% endhint %} ## What you should see ![The Broker screen](https://1085357737-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7xzJyi9JVzRwnV6JzUho%2Fuploads%2Fgit-blob-7321e43d1c63630412512e65fe4fa08cbf8c0d1c%2Fbroker.png?alt=media) **1** How many brokers are registered. The list shows the registered brokers, each with its address and its **connection status** (for example, *Online*). On a broker's detail: * the **Gateways** tab lists each enrolled site with its status; * the **Targets** tab lists each published target with its gateway, its address and the matching local port on the solution. ## How to verify it worked 1. The broker shows *Online* in the list, and **Test connection** returns the broker version and its active routers. 2. The gateway turns *online* on the **Gateways** tab within moments of the installer finishing. If it does not, the token was consumed or expired. 3. The published target appears on the **Targets** tab with its local port. 4. Opening a session from the browser connects and recording starts — the proof that the whole chain works end to end. 5. Confirm the remote site opened **no inbound port**. If someone opened one "to make it work", the reverse model is not what is carrying the traffic. ## Common errors | Symptom | Cause | Fix | | ------------------------------------------------------------ | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | The gateway never turns *online* after the installer runs | The single-use token was already consumed or has expired | Generate a new token on the **Gateways** tab and run the installer again | | **Test connection** fails right after registering the broker | Wrong host, wrong port pair, or a wrong administration token | Re-check the address and ports; re-enter the token, which cannot be read back once saved | | The broker works, but the address now needs to change | The address is baked into the certificates and enrollment tokens | Reinstall the broker. Register by DNS name from the start so a restored VM keeps its certificates valid | | A published target cannot be reached | The address was written as seen from the solution, not from the gateway | Use `IP:port` as reachable **from the gateway**, on that gateway's own LAN | | The asset registration cannot find the remote asset | The asset points at the real remote address rather than the local port | Point the asset at the local port allocated when the target was published | | An asset refuses the broker path | It is already bound to a proxy | An asset uses a proxy or a broker gateway, never both | | Access through one broker stops working | That broker's VM is unavailable | Nothing to do by hand — see Availability below | ## Availability The broker runs on **a single VM**, which holds both the control plane and the data plane. This version has no replication or automatic failover between several broker VMs. If that VM becomes unavailable, only the accesses that go through **that** broker stop. Direct-access assets, assets using a [proxy](/pam/administration/connectivity/proxy), and assets attached to another broker keep working. Recovery **needs no manual intervention**: when the broker comes back, the gateways and connectors re-dial on their own and the solution reconciles state through its periodic routines. In practice access returns in about one to two minutes. Until native high availability exists: 1. Provide **high availability at the virtualization layer**, with automatic VM restart. 2. **Back up the VM, above all its PKI.** The certificates are the root of trust for every gateway and connector. Losing the VM with no backup means reinstalling the broker and re-enrolling every remote endpoint. 3. **Always use a DNS name**, so you can point it at a restored VM and keep the certificates valid. 4. **Segment by separate brokers** per site or per criticality to reduce the blast radius. This is not failover: an asset belongs to a gateway of one specific broker and does not migrate on its own. ## Teardown and revocation | Action | Effect | | ------------------------------------ | -------------------------------------------------------------------------------- | | **Revoke** on the **Gateways** tab | Ends that site's access | | **Unpublish** on the **Targets** tab | Removes the target from the overlay | | **Unbind gateway** on a device card | Removes the device's link to a broker gateway. Unavailable when there is no link | | Session panel | Monitor and terminate live sessions in real time | Publish only the targets you need, and revoke gateways and targets that are no longer in use. Keep session recording mandatory for accesses that pass through a broker, as for any privileged access, and never share the broker administration token over an insecure channel. ## Field reference ### Registering a broker | Field | Meaning | | -------------------- | ------------------------------------------------------------------------------------------------ | | **Host** | Broker address. Use a DNS name — it is written into the certificates and cannot be changed later | | Admin port | Administration port, default `1280` | | Router port | Router port, default `3022` | | Administration token | The broker's admin token. Stored masked and encrypted, never displayed again | ### Publishing a target | Field | Meaning | | -------------- | -------------------------------------------------------------------------------------------------- | | **Gateway** | The online gateway that can see the asset on its own network | | Target address | `IP:port` reachable **from that gateway** | | Service name | Unique identifier for the published service, for example `db-prod-01` | | Local port | Dedicated high port on the solution, **12000 or above**, that the asset will be registered against | ### Per-broker actions | Action | What it does | | ------------------- | ---------------------------------------------------- | | **Installer** | Generates the installer to run on the remote machine | | **Test connection** | Checks that the solution reaches the broker | | **Rotate secret** | Rotates the broker's administration secret | | **Edit** | Changes the registration | | **Duplicate** | Creates a copy of the registration | | **Uninstall** | Undoes the installation | | **Delete** | Removes the record | **Register broker** and **Export** sit in the top bar. ## Related pages * [Gateways](/pam/administration/connectivity/gateways) — the other kind of gateway, which the solution dials into * [Proxy](/pam/administration/connectivity/proxy) — the alternative path, where the solution dials into the network * [Connectors](/pam/administration/connectivity/connectors) — an agent on the target machine itself, for an isolated host * [Authorizations](/pam/administration/access/authorizations) — granting access to a published asset * [Core concepts](/pam/get-started/core-concepts) — how assets, accounts and sessions fit together # Connectors An agent installed on the target machine itself, which dials out to a broker and makes a solitary host reachable when there is no gateway on its network. A **connector** is an agent installed **on the machine you want to reach**. It enrols that host in a [broker](/pam/administration/connectivity/broker) and publishes only itself. It is the answer for the isolated machine — the one with no gateway on its network. The screen states the purpose directly: *"Remote machines that dial out to the broker through an installed agent: solitary hosts with no gateway, made reachable and managed right here"*. ## What this is and when to use it Technically a connector is **a gateway that serves itself**. Instead of reaching other equipment on its network, it exposes the local service of its own machine — the RDP port on the loopback address, for example. The agent dials **out** to the broker from inside the machine, and the solution then reaches it back along that path. No inbound port is opened on the machine, and none on its network. Use a connector when the target is a one-off machine — a laptop, a cloud instance, a device on a home or third-party network — and installing a gateway to serve the whole network makes no sense. ### Connector or broker gateway | | Serves | Installed on | | ------------------ | ----------------------------- | ------------------------- | | **Broker gateway** | Several assets on the network | A machine on that network | | **Connector** | Only its own machine | The asset itself | They are listed separately in the console for exactly that reason. | Situation | Mechanism | | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------- | | The solution reaches a machine in the network, but not the assets | [Proxy](/pam/administration/connectivity/proxy) | | The solution cannot reach the network, and no inbound port may be opened | [Broker](/pam/administration/connectivity/broker) with a gateway at the site | | The target is a single isolated machine with no gateway on its network | **Connector** | ## Before you start * A [**broker**](/pam/administration/connectivity/broker) already registered. The connector enrols itself in it, so there is nothing to enrol into until the broker exists. * **Outbound** network access from the target machine to the broker. Nothing inbound. * Administrative rights on the target machine, to run the installer there. ## Steps 1. **Register the broker** first, if you have not already — see [Broker](/pam/administration/connectivity/broker). 2. **Get the installer.** Use **Download connector** on the Connectors screen. 3. **Run it on the target machine.** Not on a server nearby, not on a jump host — on the machine you want to reach. This is the whole distinction between a connector and a broker gateway. 4. **The agent dials out** to the broker and the connector appears in the list with its status. 5. **Link it to a device.** Until the connector is bound to an asset in [Inventory](/pam/administration/assets/inventory), it is enrolled but nobody can connect through it. The **Device** column shows *Not linked* while that is the case. 6. **Grant access** to the users or groups who need the asset. From there the session behaves like any other: mediated, recorded, audited. ## What you should see ![The Connectors screen, with no connector enrolled yet](https://1085357737-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7xzJyi9JVzRwnV6JzUho%2Fuploads%2Fgit-blob-9821c0c5bf0f8b9fd0e5f8fc29b0d13028309cea%2Fconnectors.png?alt=media) The three counters at the top read connectors, online, and linked to a device. With no broker registered the screen says so: connector tokens are generated by a broker. Three counters at the top of the screen: the total number of **Connectors**, how many are **Online**, and how many are **Linked to a device**. The list below them: | Column | Content | | ---------------- | ----------------------------------------------------------------- | | **Connector** | The connector's name, usually the host name | | **Status** | The state of the connection to the broker — *Online* or *Offline* | | **Broker** | The broker the connector is enrolled in | | **Device** | The inventory device it is bound to, or *Not linked* | | **Local target** | The local service the agent publishes | | **Actions** | The actions available for that connector | {% hint style="info" %} A connector can exist without being linked to a device. It shows as *Not linked*: enrolled in the broker, but with no inventory asset attached yet. That is a normal intermediate state, not an error — but nobody can open a session through it until the link is made. {% endhint %} ## How to verify it worked The list proves enrolment, not reachability. Check both. 1. The connector shows **Online**. If it does not, the machine has no outbound path to the broker, or the broker itself is down. 2. The **Device** column names the asset instead of *Not linked*, and the **Linked to a device** counter went up by one. 3. **Local target** names the service you meant to publish — the RDP or SSH port of that machine, not something else. 4. **Open a real session** from the browser and confirm it connects and that recording starts. That is the only check that exercises the whole chain: agent, broker, and the solution's route back. 5. Confirm the machine and its network still have **no inbound port open**. If someone opened one "to make it work", the reverse path is not what is carrying the traffic and you have lost the property you installed the connector for. ## Common errors | Symptom | Cause | Fix | | -------------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | The connector never comes *Online* | The machine has no outbound path to the broker | Allow outbound access from the machine to the broker's ports; nothing inbound is needed | | The connector was *Online* and went *Offline* | The machine is off, or the broker is unavailable | Connectors re-dial on their own when the broker returns — see Availability in [Broker](/pam/administration/connectivity/broker) | | The connector is *Online* but no one can connect | It shows *Not linked* — no inventory asset is bound to it | Link it to a device | | Several machines were meant to be reachable, only one is | The installer was run on one machine, and a connector publishes only itself | Install a connector per machine, or use a broker gateway to serve the whole network | | The connector is *Online* but the session fails | **Local target** does not point at the service actually listening on that machine | Publish the local service that is really there, on the port it really uses | | The asset refuses the connector path | It is already bound to a proxy | An asset uses a proxy or a broker path, never both | ## Field reference | Item | What it is | | ---------------------- | -------------------------------------------------------------------------- | | **Download connector** | Produces the agent installer, to be run on the target machine | | **Connector** | The connector's name, normally the host name | | **Status** | *Online* or *Offline* — the state of the outbound connection to the broker | | **Broker** | The broker this connector is enrolled in | | **Device** | The bound inventory device, or *Not linked* | | **Local target** | The local service the agent publishes on its own machine | Requirements, restated because each one is a way this fails: * The agent runs **on the target machine itself**. * The machine needs **outbound** access to the broker. * A **broker** must already be registered for the connector to enrol in. ## Related pages * [Broker](/pam/administration/connectivity/broker) — the hub the connector dials out to * [Gateways](/pam/administration/connectivity/gateways) — the jump host the solution dials into instead * [Proxy](/pam/administration/connectivity/proxy) — the alternative path, where the solution dials into the network * [Asset inventory](/pam/administration/assets/inventory) — the device a connector is linked to * [Core concepts](/pam/get-started/core-concepts) — how assets, accounts and sessions fit together # Endpoints The address and port the console hands to a client when a session opens, and why changing a port here does not move the service that is actually listening. An **endpoint** is the address and the set of ports the console gives a client when it opens a session: *this is where you dial*. The same component can have several endpoints, because a client inside the data centre and a client on the internet do not reach it at the same address. {% hint style="danger" %} **The ports on an endpoint are an announcement, not a listener.** Changing a port here changes only what the client is told to dial. It does not move the service that is actually listening — that is a property of how the component was deployed. Change one without the other and clients are sent to a port where nothing answers. {% endhint %} ## What this is and when to use it The solution's components — the core, the terminal connector, the graphical connector, the database connector and the rest — each listen somewhere. An endpoint is the record that says how a client should reach them: | Endpoint | Purpose | | ------------ | -------------------------------------------------------------- | | **Default** | The internal path, between the core and the terminal connector | | **External** | For clients outside the network | | **Private** | For a DMZ or a private network | One endpoint is selected per connection, and **routing rules** decide which, by matching an IP group. The result is handed to the client — written into the downloaded connection file for a native client, or used by the web client directly. You touch this screen in two situations: when a class of clients reaches the solution at a different address than the default assumes, and when a port has to change because 3389 or 2222 is already taken, or because a firewall standard forbids it. ## Before you start * Administrator privileges in the console. * The address each client population actually uses to reach the solution — which is often not the address the appliance knows itself by. * For a port change, **access to the deployment**. The listening side is not configurable from the console, and the change is not finished until both sides agree. {% hint style="warning" %} Treat a port change as a maintenance window. Restarting or recreating the component that listens **cuts live sessions** on that protocol, and a session killed that way can be left recorded as still open. {% endhint %} ## Steps To make a class of clients reach the solution at a different address, add or edit the endpoint for that network and give it the host name those clients resolve, then add a routing rule that selects it for the matching IP group. To change a **port**, both sides have to move, in this order: 1. **Change the listener first.** The port the component actually publishes is fixed by its deployment. Updating it is a deployment task — it belongs with whoever installed the platform, not with the console operator. 2. **Then change the announcement** on the endpoint, so clients are told the new port. 3. **Re-test with a real session.** Nothing else proves the two halves now agree. {% hint style="info" %} Databases behave slightly differently: each database connector has its own service endpoint, and the port is part of how a database session is routed. Some database platforms therefore have no editable port at all, because the port itself is the routing key. {% endhint %} ## What you should see Endpoints are listed per component, alongside the component's own state: | Field | Meaning | | ------------------ | --------------------------------------------------------------------------------------- | | **Name** | The component's unique identifier | | **Type** | What it is — core, terminal, graphical, database, virtual application, video processing | | **Status** | *Online*, *Offline*, or an error state | | **Last heartbeat** | When it last reported in | | **Version** | The build it is running | | **Endpoints** | The connection addresses defined for it, per network | A component that is *Offline* has no working endpoint regardless of what the endpoint record says. ## How to verify it worked Reading the endpoint record back tells you nothing — it will show whatever you typed. Verify against a session. 1. **Open a real session** on the protocol you changed, as a user from the client population the endpoint is meant for. Not from the console host, and not from your own network if that is a different network. 2. **Read the address the client was given.** For a native client, the downloaded connection file carries the host and port; for the web client, the session simply connects or it does not. Confirm it is the address and port you intended. 3. **Confirm something is listening there.** If the client is sent to the right place and the connection is still refused, the announcement moved and the listener did not. 4. **Test each client population separately.** An internal client and an external client can resolve to different endpoints, and fixing one commonly breaks nothing but also proves nothing about the other. {% hint style="warning" %} A local port redirection does not show up in a listening-socket listing — it diverts the packet before it reaches a socket. If the port looks unused but traffic arrives anyway, check the host's NAT rules, not its socket table. {% endhint %} ## Common errors | Symptom | Cause | Fix | | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | The client opens and immediately fails to connect, on a port you just changed | New announcement, old listener: the client is being sent to a port where nothing answers | Move the listener to the new port, in the deployment, then retest | | Clients still reach the old port after the deployment was changed | New listener, old announcement: the connection string still carries the previous port | Update the endpoint so the announcement matches | | Some clients connect and others cannot | They resolve to different endpoints, and only one is correct | Check which endpoint each population actually gets before changing ports | | A client is given an unroutable internal address | The default endpoint is being used for clients outside the network | Define the external endpoint and a routing rule that selects it for those addresses | | The port change was reverted after a reinstall or an upgrade | The installer re-applies the deployment's own port and rewrites the announcement with it | Record any non-default port as part of the installation parameters for that machine, so a re-run keeps it | | The port appears unused, but connections still arrive on it | A local redirection is diverting traffic before the socket | Inspect the host's NAT rules rather than its listening sockets | | Sessions were cut and one shows as still open | The listening component was restarted or recreated with live sessions on it | Do port changes in a maintenance window; a session left open this way has to be closed out administratively | ## Field reference | Item | What it is | | ------------------------- | ---------------------------------------------------------------------------------------------------------------- | | **Default** endpoint | The internal path, between the core and the terminal connector | | **External** endpoint | The address used by clients outside the network | | **Private** endpoint | The address used from a DMZ or a private network | | **Routing rule** | Binds an IP group to an endpoint, so one endpoint is selected per connection | | Port fields | The port **announced** to the client. Never the port the component listens on | | Database service endpoint | Each database connector has its own; for some database platforms the port is the routing key and is not editable | ## Related pages * [Ports and protocols](/pam/reference/ports) — the ports used to reach *assets*, which are a separate question from these * [Connection methods](/pam/administration/sessions/connection-methods) — which clients a user may launch, and therefore which endpoint they will be handed * [Proxy](/pam/administration/connectivity/proxy) — reaching assets through a jump machine * [Broker](/pam/administration/connectivity/broker) — reverse connectivity, where the path is established outbound instead * [Core concepts](/pam/get-started/core-concepts) — how the components, assets and sessions relate # Behavior analytics | Page | What it covers | | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | | [Risk score](/pam/administration/ueba/risk-score) | The 0–100 score behavior analytics assigns to each anomaly, what each event is worth, and how the score drives automatic mitigation. | | [Detection and mitigation policy](/pam/administration/ueba/policy) | Configure how DataDike PAM detects anomalous user behavior and what it does automatically when the risk score crosses a threshold. | # Risk score The 0–100 score behavior analytics assigns to each anomaly, what each event is worth, and how the score drives automatic mitigation. ## What the score represents Every anomaly the behavior analytics module detects carries a score from 0 to 100. It is **not a percentage**. It is an operational severity rating, used for two things: * ordering events, so an analyst sees what matters most first * triggering mitigation, by comparing the score against the configured thresholds A low score means a mild departure from the user's usual behavior. A high score means a pattern far from the baseline, worth containing. ## Bands | Range | Classification | What it is for | | ------ | -------------- | ------------------------------------------------------------------- | | 0–49 | Low | Record the event and keep visibility for later analysis | | 50–69 | Medium | Raise an alert and surface the event for operational review | | 70–84 | High | Allow containment, such as terminating the session | | 85–100 | Critical | Allow stronger action, such as termination plus credential rotation | ## Score per event Each kind of detected behavior carries a default severity: | Event | Score | Band | | ---------------------------------------- | ------ | ------------- | | First access to a new asset | 35 | Low | | Access outside expected hours | 45 | Low | | Login from a new IP | 50 | Medium | | Login from a new location | 50 | Medium | | Session started from a new IP | 55 | Medium | | Spike in session volume | 60 | Medium | | Burst of risky commands | 65 | Medium / high | | Excessive failed logins | 70 | High | | Impossible travel | 85 | Critical | | Event with strong evidence of compromise | 90–100 | Extreme | {% hint style="info" %} **Impossible travel** scores 85 because successive accesses from locations that cannot both be reached in the elapsed time mean the credential is being used by more than one person. {% endhint %} ## What counts as suspicious Suspicious behavior is activity that departs from the expected pattern for that user, account, asset, or session. The module compares recent events against the historical baseline and scores the deviation. Examples: * access outside the hours the user normally works * login from an IP address or a city not seen before * access to an asset with no prior history for that user * an unusual rise in session volume * several authentication failures in a short interval * a concentrated run of commands classified as risky * successive accesses from locations incompatible in time ## How the score drives mitigation The policy defines two thresholds, both compared against the anomaly's score. **Session termination** is a *containment* action. It interrupts the running session when the score reaches the **kill-session score threshold**, default **80**. Events below it are still recorded and alerted, but the session continues. **Credential rotation** is a *revocation* action. It changes the secret of the account involved, invalidating the previous password. The default is **90** — higher than termination, because the operational impact is greater. Termination stops the access in progress; rotation invalidates the credential for every future use, including integrations that depend on it. When both thresholds are reached, containment runs first: 1. the running session is terminated 2. the associated credential is rotated 3. the mitigation applied is recorded on the anomaly 4. the audit trail keeps the automation as the actor ### Threshold ranges | Field | Minimum | Maximum | Default | | ----------------------------- | ------- | ------- | ------- | | Kill-session score threshold | 50 | 100 | 80 | | Credential rotation threshold | 50 | 100 | 90 | The minimum of 50 keeps weak signals from triggering aggressive automation. The maximum of 100 allows restricting automatic action to maximum-severity events only. {% hint style="warning" %} Automatic rotation changes the password of a managed account with no human in the loop. Before enabling it, check which integrations consume that credential, and keep the emergency access account outside the policy's reach. {% endhint %} ## Choosing thresholds A conservative path: 1. Leave automatic mitigation off for a few weeks and observe which scores actually appear in your environment. 2. Enable session termination first, at the default 80. 3. Only then enable credential rotation, starting at 90 or above. Lowering the rotation threshold into the 70s means including events such as excessive failed logins — which also happen when a user simply mistypes. ## Analyze now The **Analyze now** button on the policy screen runs detection on demand, without waiting for the periodic run. Anomalies found are recorded and evaluated against the current policy: if automatic mitigation is enabled and the scores reach the thresholds, the actions are applied in that same run. ## Related pages * [Detection and mitigation policy](/pam/administration/ueba/policy) — the screen and its fields * [Rotate credentials](/pam/administration/accounts/rotation) * [Live monitoring](/pam/administration/sessions/live-monitoring) * [Audit trail](/pam/administration/audit/audit-trail) # Detection and mitigation policy Configure how DataDike PAM detects anomalous user behavior and what it does automatically when the risk score crosses a threshold. {% hint style="info" %} Three controls on this screen — Request reauthentication, Automatic credential rotation and Revoke credentials automatically — are delivered in a forthcoming release. Every other setting described on this page is available today. {% endhint %} ## What this is and when to use it The behavior analytics module builds a baseline of how each user normally works — when they connect, from where, to which assets — and scores any departure from it. The policy is where you decide two separate things: **how sensitive the detection is**, and **what the solution does on its own** when a score crosses a line you set. Configure it when you first roll out behavior analytics, and revisit it when the volume of anomalies is either too noisy to review or too quiet to be useful. Detection and mitigation are independent. You can run detection alone — the solution records the anomaly and raises an alert, and a human decides what to do. Automatic mitigation is what lets it act without waiting for that human. ## Before you start * The **SYSADMIN** profile. The policy is not visible to other profiles. * At least one baseline window of session history. On a new installation the scores are unreliable until users have worked through a full window. * If you plan to enable automatic credential rotation, at least one credential rotation task must already exist and be active. The policy is the trigger; the task is what actually rotates. See [Rotate credentials](/pam/administration/accounts/rotation). ## Steps 1. Open **Policies › UEBA**. 2. Turn on **Detection enabled**. Nothing is scored while this is off. 3. Set **Baseline window (days)** to the period the solution should treat as normal behavior. Thirty days covers a monthly work cycle; shorter windows react faster but flag more false positives. 4. Set **Off-hours (start → end)** to the hours outside which access is unusual for your organization. The range wraps midnight, so `18 → 8` means six in the evening until eight the next morning. 5. Set **Failed login threshold** to the number of failed logins within twenty-four hours that should be treated as a burst. 6. Decide whether the solution should act on its own. If it should, turn on **Automatic mitigation**. Leave it off to run in alert-only mode. 7. With automatic mitigation on, set each action and its threshold: * **Kill-session score threshold** — the score at or above which a live session is terminated. * **Automatic credential rotation** and **Credential rotation threshold** — the score at or above which every secret defined in the rotation tasks is rotated. * **Revoke credentials automatically** — revokes credentials linked to the user or the session. 8. Click **Save**. ## What you should see The counters at the top of the screen — **Open**, **High risk** and **Total** — reflect anomalies already recorded. They do not change when you save the policy; they change on the next analysis run. ![The UEBA policy screen with detection enabled and automatic mitigation off](https://1085357737-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7xzJyi9JVzRwnV6JzUho%2Fuploads%2Fgit-blob-b253259551396e7d7affb12598adf82dd68a88db%2Fueba-policy-full.png?alt=media) ## How to verify it worked Saving the policy is not proof that it is in force. Verify against a real anomaly: 1. Click **Analyze now** and wait for the run to finish. 2. Open **Audit › UEBA**. 3. Open any anomaly and read the **Mitigation** field. The field states which action was applied and why. With automatic mitigation off it reads `Alert only — auto-mitigation disabled`. With it on, the field names the action the solution took, and a session terminated by the policy also appears as closed in **Sessions › Online**. If the Mitigation field still shows the previous behavior, the policy did not save — reopen the screen and confirm the values persisted. ## Common errors | Symptom | Cause | Fix | | ------------------------------------------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------- | | No anomalies after **Analyze now** | Less history than the baseline window | Wait for a full window, or shorten the window temporarily | | Everything is flagged as an anomaly | Baseline built during an atypical period, such as a migration | Lengthen the baseline window and re-run the analysis | | Sessions are not terminated although the threshold is reached | **Automatic mitigation** is off; the individual action does nothing on its own | Turn on Automatic mitigation | | A value is refused when you type it | The field is outside its accepted range | See the range in the field reference below | ## Field reference | Field | What it does | Accepted values | Default | | -------------------------------- | ---------------------------------------------------------------------------------------- | --------------- | ------- | | Detection enabled | Master switch for scoring. Nothing is analyzed while off | On, Off | On | | Automatic mitigation | Master switch for every automatic action. While off the solution only records and alerts | On, Off | Off | | Request reauthentication | Challenges the user to authenticate again | On, Off | Off | | Automatic credential rotation | Rotates every secret defined in the rotation tasks | On, Off | Off | | Revoke credentials automatically | Revokes credentials linked to the user or the session | On, Off | Off | | Baseline window (days) | Period treated as normal behavior | 7 to 180 | 30 | | Off-hours (start → end) | Hour range treated as outside working hours. Wraps midnight | 0 to 23, each | 18 → 8 | | Failed login threshold | Failed logins within 24 h that count as a burst | 3 to 50 | 5 | | Kill-session score threshold | Score at or above which a session is terminated | 50 to 100 | 80 | | Credential rotation threshold | Score at or above which credentials are rotated | 50 to 100 | 90 | ## Related pages * [Risk score](/pam/administration/ueba/risk-score) — how the score is calculated and what each band means * [Rotate credentials](/pam/administration/accounts/rotation) — the task that performs the rotation * [Audit trail](/pam/administration/audit/audit-trail) — where mitigation actions are recorded * [Live monitoring](/pam/administration/sessions/live-monitoring) — terminating a session by hand # Audit | Page | What it covers | | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Audit trail](/pam/administration/audit/audit-trail) | Where the solution writes every login, command, password change, file transfer and administrative operation, how long those records are kept, and how to consult or forward them. | | [Session recordings](/pam/administration/audit/recordings) | Find, replay, and download the recording of a finished session, and understand what is captured for each protocol and how long it is kept. | | [Reports](/pam/administration/audit/reports) | Turn the audit data into a document: ten operational reports, seven compliance packages, on demand or on a cron schedule, as PDF, XLSX, or CSV. | # Audit trail Where the solution writes every login, command, password change, file transfer and administrative operation, how long those records are kept, and how to consult or forward them. ## What this is and when to use it The audit trail is the set of searchable records the solution writes for everything that happens through it: who logged in and from where, which commands ran inside a session, which passwords changed, which files moved, and which administrative objects were created, edited, or deleted. Use it when you need to answer a question about the past — "who restarted that host on Friday", "was this account used outside business hours", "who changed that authorization rule". Three things in the **Audit** area are easy to confuse: | Area | What it holds | | ---------------------------------------------------------- | ------------------------------------------------------------------------ | | **Audit trail** (this page) | The records themselves — text, searchable, filterable, exportable | | [Session recordings](/pam/administration/audit/recordings) | The video-style replay of a session, played back from the session record | | [Reports](/pam/administration/audit/reports) | Packaged extracts of the same data, generated on demand or on a schedule | The audit trail is the source; recordings and reports are two ways of looking at it. ## Before you start * Your role must grant access to the **Audit** area. Reading other people's records is gated by RBAC — see [Roles](/pam/administration/identities/roles). * Retention is a system-wide setting, configured in **System settings › Retention**. Records older than the retention window are no longer there to find. * To forward records off the appliance, the syslog or Elasticsearch target must be reachable from the nodes. ## Where each record lives | Record | Console location | What it answers | | -------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | **Login log** | **Audit › Console › Login log** | Who tried to authenticate, with which method, from which address, and whether it succeeded | | **Session records** | **Audit › Console › Session records** | Every session opened on an asset, live and historical, with replay and download | | **Online users** | **Audit › Console › Online users** | Who is connected to the console right now, with the option to disconnect them | | **Password changes** | **Audit › Console › Password changes** | Which account had its password changed, by whom or by which automation, from which address | | **Action log** | **Audit › Log audit › Action log** | Creation, modification, and deletion of objects — users, assets, rules, permissions | | **Commands** | **Audit › Sessions › Keylogger** | Every command typed in an SSH or Telnet session, with its risk classification and a link back to the session | | **File transfers** | **Audit › Sessions › Transfers** | Uploads and downloads made during sessions, with a copy of the file | | **Job list** | **Audit › Operation audit › Job list** | The automations configured to run, with their schedules | | **Executions** | **Audit › Operation audit › Executions** | Each run of each automation, whether it finished, and whether it succeeded | The **Dashboard** at the top of the **Audit** area is the consolidated view of the same data over **Today**, **7 days**, or **30 days**: total commands and how many of them were risk commands, scheduled and running jobs, online and total sessions, transferred files, accesses, operation log entries, and passwords changed — followed by a table of the most recent sessions. ## What gets recorded The trail is grouped into families of events: | Family | Events | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Operational activity** | Access, access attempt, blocked access, password change | | **Configuration activity** | Changes to system and object configuration | | **Audit activity** | Access to reports, to command records, to transferred files, and to session recordings | | **Authentication activity** | Successful and failed password authentications, passwords unused for more than a given number of days, passwords used, passwords changed, account discovery, account registration, account use, account association | | **Access RBAC** | Users attached to a permission, users removed from a permission, changes to access permissions | {% hint style="info" %} Reading the trail is itself part of the trail. Opening a recording, a command record, a transferred file, or a report is written as an *audit activity* event, so consulting evidence is as traceable as producing it. {% endhint %} ### Retention Records are searchable from the console and kept according to the policies in **System settings › Retention**. Set that window before you need it: a question asked outside the window cannot be answered afterwards, and shortening retention discards history immediately. ### Forwarding to a SIEM Records can be sent to an external collector, so that the trail survives independently of the appliance. Supported destinations are syslog over UDP, TCP, or TLS, Elasticsearch, e-mail, and plain text export. | Protocol | Default port | | ---------- | ------------ | | Syslog UDP | 514 | | Syslog TCP | 514 | | Syslog TLS | 6514 | The record format follows a common standard and is consumed without a custom parser by the usual collectors — Splunk, IBM QRadar, Microsoft Sentinel, Elastic Security and the ELK stack, OpenSearch, Google Security Operations, Securonix, LogRhythm, Graylog, Wazuh, Loki and Grafana, Fluentd and Fluent Bit, rsyslog and syslog-ng, SolarWinds, ManageEngine, and Nagios. Configure the destination in **System settings** — see [Syslog and SIEM](/pam/administration/integrations/syslog-and-siem). ## Steps Investigating an incident follows the same shape in every log: 1. Open the log that holds the kind of evidence you need, from the table above. 2. Narrow the **period** with the date selector at the top of the page — start date and end date. Every log defaults to a recent window, not to everything. 3. Search by the identifier you actually have. **Login log** searches by username; **Session records** searches by user, asset, user ID, asset ID, account, protocol, login origin, remote address, and terminal. 4. Sort by any column to bring the extremes together — repeated failures on one username, or every session on one asset. 5. Follow the record to its context. From a command in **Keylogger**, use **Go to session** to reach the session it was typed in, and from there its [recording](/pam/administration/audit/recordings). From **Transfers**, download the copy of the file that moved. 6. Export the result if the evidence has to leave the console, or build a repeatable extract in [Reports](/pam/administration/audit/reports) instead. ## What you should see ![The Operate logs screen, with the change history and one record open](https://1085357737-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7xzJyi9JVzRwnV6JzUho%2Fuploads%2Fgit-blob-0ee200912e806bd3de78865d9ed1a1ba8505ca3b%2Faudit-trail.png?alt=media) **1** How many records the current filter returns. **2** One record, with the action and the resource it touched. **3** The resource type, which is how you narrow to one kind of object. **4** The total behind the filter. Each log is a table you can filter, sort, and export. Two details are worth knowing before you read them: * In **Session records**, live sessions are under **Online session** and finished ones under **Historical sessions**. A session that ended appears in the second tab with **Replay** and **Download** in the **Operation** column. * In **Keylogger**, the **Risk level** column shows how the command was treated by policy: **Accept** in green means it was allowed, **Reject** in red means it was blocked for violating a rule. The classification comes from [command inspection](/pam/administration/access/command-filtering), so a red row is a blocked attempt, not a command that ran. ## How to verify it worked Do not trust the presence of a log page; prove that it is capturing. Each check below is one action followed by one lookup: 1. **Login log** — sign in once with a deliberately wrong password, then sign in correctly. Both attempts must appear, with **Failure** carrying a reason and **Success** carrying the authentication method. 2. **Keylogger** — open an SSH session, run a harmless command and one command your policy rejects. Both must be listed, the second classified **Reject**, and **Go to session** must lead back to that session. 3. **Password changes** — rotate one managed account, then confirm the account appears with the automation or user as **Modifier** and the source address filled in. 4. **Action log** — change any object, such as a user's group, and confirm the modification is recorded against your username. 5. **Dashboard** — set the filter to **Today** and confirm the counters moved by the actions you just performed. If you forward to a SIEM, repeat step 1 and confirm the event arrives on the collector. A record present in the console and absent on the collector is a transport or port problem, not an auditing problem. ## Common errors | Symptom | Cause | Fix | | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | | The event you are looking for is not in the log | The date filter excludes it, or it is older than the retention window | Widen the period first; if the window has passed, the record is gone — raise retention in **System settings › Retention** | | A session is live on the asset but missing from the trail | The session was never registered as active, so cleanup routines can close it out of sight | Look for it under **Historical sessions**; recurring cases are an installation problem, not a filter problem | | Commands are missing for a session | Command capture covers SSH and Telnet; graphical protocols leave a recording, not a command list | Use the [recording](/pam/administration/audit/recordings) for RDP, VNC, and web sessions | | A command shows as **Reject** but the user says it ran | The row is the blocked attempt, not an execution | Confirm against the session recording; blocked commands never reach the target | | You cannot see another user's records | RBAC does not grant audit visibility to your role | Adjust the role — see [Roles](/pam/administration/identities/roles) | | Nothing arrives at the SIEM | Wrong protocol or port, or the collector is unreachable from the nodes | Check against 514/UDP, 514/TCP, 6514/TLS and test reachability from every node | ## Field reference ### Login log | Field | What it holds | | --------------------- | ----------------------------------------------------------------------------- | | Username | The account that attempted to log in | | Authentication method | How it authenticated — password, MFA, and so on | | Reason description | Detail for a failure, for example that the username or password was incorrect | | Status | **Success** or **Failure** | | Login date | Date and time of the attempt | ### Session records | Field | What it holds | | ---------- | ---------------------------------------------------------- | | Number | Unique session identifier | | User | Who opened the session | | Target | The asset accessed, with its name and IP address | | Account | The credential used | | Protocol | SSH, RDP, SFTP, HTTP, and others | | Start date | When the session began | | Operation | **Replay** to watch the recording, **Download** to save it | ### Online users | Field | What it holds | | --------------------- | ------------------------------------------------- | | User | The connected user | | Authentication method | How they authenticated | | Login date | When they connected | | Active | Whether the session is still active | | Operation | **Disconnect** to end that user's console session | {% hint style="warning" %} You cannot disconnect yourself from **Online users** — the attempt is refused because it is your own session. The list covers users connected through the web console; sessions on assets are ended from **Session records** or from [live monitoring](/pam/administration/sessions/live-monitoring). {% endhint %} ### Password changes | Field | What it holds | | -------------- | --------------------------------------------------------------------------------------------- | | User | The account whose password changed | | Modifier | The user or process that changed it — the account itself, an administrator, or a rotation job | | Remote address | Source address of the change | | Date | When it happened | ### Keylogger | Field | What it holds | | ---------- | ---------------------------------------------------------------- | | Command | The command as typed | | Risk level | **Accept** (allowed by policy) or **Reject** (blocked by a rule) | | User | Who typed it | | Assets | Where it ran | | Account | The credential used | | Session | **Go to session**, a link to the originating session | An asset tree on the right of the page narrows the list to one asset, which is the fastest way to review everything typed on a single host. ### Transfers | Field | What it holds | | ------------------ | ------------------------------------------------------ | | ID | Unique transfer identifier | | User | Who transferred the file | | Assets | Source or destination asset | | Account | The credential used | | Operation | Direction of the transfer — **Download** or **Upload** | | File name | Name of the file transferred | | Operation (button) | Retrieves a copy of the transferred file | ### Job list and Executions | Field | What it holds | | ------------------ | --------------------------------------------------------------------- | | Name | Name of the job | | Command | The command configured to run, for example `win_shell:reboot -s -t 0` | | Type | Command, file upload, and so on | | Periodic execution | Cron expression for the schedule, for example `0 0 * * *` | | Interval | Interval between runs | | Creator | Who or what started an execution | | Task type | `adhoc` for a manual run, `upload_file` for an upload | | Finished | Whether the run completed | | Was it successful? | Whether the run succeeded | | Operation | **View** for the run detail, **Stop** to interrupt a running task | ## Related pages * [Session recordings](/pam/administration/audit/recordings) — the replay behind a session record * [Reports](/pam/administration/audit/reports) — repeatable extracts of these same records * [Command inspection](/pam/administration/access/command-filtering) — where the **Accept** and **Reject** classification comes from * [Syslog and SIEM](/pam/administration/integrations/syslog-and-siem) — forwarding the trail off the appliance * [Risk score](/pam/administration/ueba/risk-score) — the behavioural reading of the same events # Session recordings Find, replay, and download the recording of a finished session, and understand what is captured for each protocol and how long it is kept. ## What this is and when to use it Every session the solution brokers is recorded, whatever the protocol — SSH, RDP, VNC, and database sessions included — and can be replayed afterwards as video with a timeline. The recording is the evidence you use when a text log is not enough: what a person actually saw and did on a graphical desktop, in what order, and for how long. Use it for incident investigation, for change verification, and for the compliance requirement that privileged activity be reviewable after the fact. Two distinctions save time here: * A recording is **after the fact**. Watching a session while it is still running, pausing it, or cutting it off is [live monitoring](/pam/administration/sessions/live-monitoring). * A recording is **the whole screen or terminal**. The searchable list of commands typed in SSH and Telnet sessions is a separate record — see [Audit trail](/pam/administration/audit/audit-trail). Search the command list to find the session, then open the recording to see the context. ## Before you start * Recordings must actually be stored. The destination is a storage backend, not a per-session switch — see [Session recording](/pam/administration/sessions/recording). A session routed to the **null** backend still leaves a session record, with no replay behind it. * Your role must grant audit visibility. Replaying someone else's session is gated by RBAC, in the same way as watching a live session — see [Roles](/pam/administration/identities/roles). * Retention applies. Recordings are kept for the window configured in **System settings › Retention**; past that, the session record may remain while its recording does not. ## Steps 1. Open **Audit › Console › Session records**. The dedicated list under **Audit › Sessions › Recordings** shows the same material filtered to recorded sessions. 2. Switch to the **Historical sessions** tab. **Online session** holds sessions that are still running and has no replay — those are handled from [live monitoring](/pam/administration/sessions/live-monitoring). 3. Narrow the list before you scroll it. You can filter by user, asset, user ID, asset ID, account, protocol, login origin, remote address, and terminal, plus a start and end date. 4. Use **Replay** in the **Operation** column to watch the session in the browser, or **Download** to save a copy for an evidence package. 5. To retrieve a file that moved during the session, use **Transfers** instead of the recording — it keeps a copy of each uploaded and downloaded file. See [File transfer](/pam/administration/sessions/file-transfer). ## What you should see The player opens on the session and plays it back with a timeline you can seek through, so a two-hour session can be reviewed at the few moments that matter. The session record around it carries the identity of the session — user, asset and IP, account, protocol, start time, duration. **Download** produces a file of the session, not a screenshot: it is the same material as the replay, for keeping outside the console. {% hint style="info" %} Opening a recording is itself an audited event. It is written to the action log as an *audit activity*, together with access to reports, command records, and transferred files, so a reviewer's access to evidence is traceable. {% endhint %} ## How to verify it worked Verify the pipeline end to end, on a session you create for the purpose, rather than assuming an old session is representative: 1. Open a session to the asset whose recording you want to prove — one session per protocol you care about. 2. Do something visually identifiable, then close the session. 3. In **Session records**, confirm the session has left **Online session** and is listed under **Historical sessions** with **Replay** available. 4. Play it back and confirm the identifiable action is there and that playback runs to roughly the recorded duration — a replay that stops early is a different problem from one that never starts. 5. Click **Download** and confirm you receive a file. 6. Open the action log in [Audit trail](/pam/administration/audit/audit-trail) and confirm your own access to the recording was logged. Step 3 is the one that catches the common case: if the session stays under **Online session** after you disconnected, the session was never closed properly and the recording will not be offered. ## Common errors | Symptom | Cause | Fix | | ----------------------------------------------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | The session is listed but **Replay** is not offered | Recording was not enabled for that asset or platform when the session ran | Enable it in [Session recording](/pam/administration/sessions/recording); past sessions cannot be recovered | | The session never appears under **Historical sessions** | The session did not close cleanly and is still held as online | Check the **Online session** tab; if it lingers after the user disconnected, the session needs to be closed before its recording is available | | The recording is gone but the session record is there | The retention window for recordings has passed | Raise the window in **System settings › Retention** before you need the evidence, not after | | You can replay your own sessions but not other people's | RBAC does not grant audit visibility to your role | Adjust the role — see [Roles](/pam/administration/identities/roles) | | You need the file a user copied, not the video of them copying it | Recordings are screen and terminal material only | Retrieve the copy from **Transfers** — see [File transfer](/pam/administration/sessions/file-transfer) | ## Field reference Columns on the session record that carries the recording: | Field | What it holds | | ---------- | ----------------------------------------------- | | Number | Unique session identifier | | User | Who opened the session | | Target | The asset accessed, with name and IP address | | Account | The credential used | | Protocol | SSH, RDP, SFTP, HTTP, and others | | Start date | When the session began | | Duration | Total length of the session | | Operation | **Replay** to watch it, **Download** to save it | Filters available above the list: | Filter | Notes | | ------------------ | -------------------------------------------------------------------- | | User / User ID | The person who opened the session | | Assets / Asset ID | The target | | Account | The credential used | | Protocol | Narrows to one protocol, useful when only some platforms record | | Login origin | Where the session was launched from | | Remote address | Client source address | | Terminal | Which component brokered the session | | Start and end date | The period; set it first, since the list defaults to a recent window | ## Related pages * [Session recording](/pam/administration/sessions/recording) — where recordings are stored, and how to deliberately not store them * [Live monitoring](/pam/administration/sessions/live-monitoring) — watching, pausing, and ending a session in progress * [Audit trail](/pam/administration/audit/audit-trail) — the command, login, and file transfer records around the recording * [File transfer](/pam/administration/sessions/file-transfer) — copies of the files that moved during a session * [Reports](/pam/administration/audit/reports) — packaging session evidence for an audit # Reports Turn the audit data into a document: ten operational reports, seven compliance packages, on demand or on a cron schedule, as PDF, XLSX, or CSV. ## What this is and when to use it A report turns the audit data into a file somebody outside the console can read. Seventeen generators ship with the product: ten **operational** reports over sessions, logins, commands, credentials, accounts, rotations, transfers, approvals and automations, and seven **compliance** packages that map a framework's controls to the operational reports that evidence them. Use a report when the audience is not sitting at the console: an auditor asking for the quarter's privileged sessions, a manager who wants the monthly account inventory, a framework assessment that needs the same extract every month without anybody remembering to produce it. If you are investigating one incident, search the [audit trail](/pam/administration/audit/audit-trail) instead. It is faster and far more precise. Reports are for repeatable, shareable extracts of the same records. The area sits in the **Audits** profile, under two menu entries: | Menu | What it does | | --------------------- | ------------------------------------------- | | **Audit › Builder** | Generates a report now and downloads it | | **Audit › Scheduled** | Generates on a cron schedule and e-mails it | {% hint style="info" %} The menu entry reads **Builder** but the page it opens is headed **Report Center**. They are the same screen. {% endhint %} ## Before you start * A role that grants access to the audit area. * The data has to exist. A report can only cover the period still inside the retention window set in **System settings › Retention**. * For scheduled delivery, the system must be able to send e-mail, and you need the recipient addresses. * Generating a report is itself audited. It appears in the operation log as a `create` on **Report run**, which is also how you find out who else has been pulling reports. ## What every report contains Whatever the type and whatever the format, the file opens with the same header block. It is what makes the file usable as evidence months later: | Header line | What it holds | | ------------ | ----------------------------- | | Report | The report's own name | | Organisation | The tenant the data came from | | Period | The window you asked for | | Generated at | Timestamp of generation | | Generated by | The user who ran it | After the header, an operational report carries a **summary** of counters and then one detail table. A compliance package carries a **control map** and then the operational reports it cites, embedded in the same file. ## Operational reports Ten generators. The summary column lists the counters each one puts above its table. | Report | Summary counters | Detail columns | | --------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------- | | Session activity | Total sessions, closed, recorded, by protocol | User, asset, account, protocol, origin, IP, start, end, duration, closed, recorded, commands | | Commands and violations | Total commands, by risk | Date, user, asset, account, risk, command | | Access and authentication | Total logins, success, failure, with MFA | Date, user, type, IP, location, MFA, result, reason, backend | | Credential retrieval | Retrievals, distinct consumers | Date, application or user, account or resource, source IP, action | | File transfer | Total transfers, uploads, downloads, failures | Date, user, asset, account, operation, file, success | | Password rotation | Password changes | Date, account or user, changed by, IP | | Account and vault inventory | Total accounts, privileged, with a secret in the vault | User, asset, privileged, auto-rotation, has secret, version, updated | | Configuration trail | Total operations, by action | Date, user, action, type, resource, IP | | Approvals and JIT access | Total requests, by status | Date, title, type, requester, status | | Automation runs | Automation runs, completed or successful | Date, task, status, completed | {% hint style="info" %} **Account and vault inventory** is the one assessors ask for. The `auto-rotation`, `has secret` and `updated` columns together turn "we rotate credentials" into per-account evidence, and they expose the accounts that rotation has quietly been missing. {% endhint %} ## Compliance packages Seven frameworks. A compliance package is not a separate dataset: it is a **control-to-evidence map followed by the operational reports that serve as the evidence**, bundled into one file. So a PCI-DSS report contains the full Access and authentication, Credential retrieval, Session activity, Password rotation and Configuration trail reports, each under its own `== section ==` heading, preceded by the table that says which control each one answers. | Package | Controls mapped | Operational reports embedded | | ---------------------- | --------------- | ---------------------------- | | PCI-DSS v4.0 | 8 | 5 | | SOC 2 (Trust Services) | 7 | 5 | | HIPAA Security Rule | 5 | 4 | | ISO/IEC 27001:2022 | 7 | 5 | | LGPD (Lei 13.709/2018) | 5 | 4 | | NIST SP 800-53 Rev.5 | 16 | 8 | | CIS Controls v8 | 12 | 8 | The full control-by-control map for all seven is in [Compliance mappings](/pam/reference/compliance-mappings). {% hint style="warning" %} A compliance package is **evidence for an assessment, not an assessment**. It shows what the platform recorded against a list of controls. It does not score you, it does not find gaps, and it is not a certification. {% endhint %} ## Steps ### Generate now 1. Open **Audit › Builder**. 2. Use **Generate report**. The dialog takes three inputs, and only three. 3. **Report type**: pick from the two groups, **Operational** or **Compliance**. 4. **Period**: a **From** and a **To** date. 5. **Format**: **PDF**, **XLSX** or **CSV**. PDF for the document you hand over, XLSX or CSV for the extract someone will filter themselves. 6. Use **Generate & download**. The file is produced and downloaded from the same screen, and a row appears in the history. {% hint style="warning" %} There is no scope filter. The dialog offers report type, period and format, and nothing else: you cannot narrow a report to one user, one asset or one protocol at generation time. Generate the whole period and filter the XLSX or CSV yourself. {% endhint %} ### Schedule it 1. Open **Audit › Scheduled**, then **New schedule**. 2. **Name** it for the thing it produces, not for the schedule. 3. **Report type** and **Format**, the same choices as the builder. 4. **Window (days)**: how far back each run reaches. The report covers the last N days at run time. Default is 7. 5. **Cron**: `minute hour day month weekday`. The default `0 6 * * 1` is Mondays at 06:00. Pick a window when the platform is quiet, because a wide report over a long period is a heavy query. 6. **Recipients (e-mail)**: type an address and press Enter, once per recipient. 7. Leave **Active** on, and **Confirm**. Match the window to the cron. A `Window (days)` of 7 on a monthly cron leaves three weeks uncovered every month, and nothing in the console warns you. ## What you should see In **Builder**, the file arrives in the browser as soon as generation finishes, and the history gains a row. Select any row and the right-hand pane shows its report type, format, status, **row count**, period, date and who generated it. The row count is the useful number there. A report that generated successfully with zero rows is not an error, and it looks identical to a working report until you open it. In **Scheduled**, the entry lists its name, report type, cron and recipients, with its last run. {% hint style="warning" %} **The run keeps its file.** Downloading from a history row returns the file that was produced at generation time, not a fresh run against the data as it is now, so what you re-send next month is what you sent originally. There is one gap worth knowing. If writing that file to storage fails, the run is still marked **successful**, with its row count, and only the download reveals the problem by reporting the file as unavailable. A history row that will not download is that case, and the report has to be generated again. {% endhint %} ## How to verify it worked A report that generates is not yet a report that is right. Check the content, not the download. 1. Open the file and confirm the **Period** and **Organisation** in its header match what you asked for. A report over the wrong month is the most common defect and the least visible one. 2. Compare the summary counters against the row count shown in the history pane. They should agree. 3. Cross-check one row against the source. Take a session from Session activity and find the same session in [Session recordings](/pam/administration/audit/recordings); take an account from the inventory and confirm it against [Managed accounts](/pam/administration/accounts/managed-accounts). If the row is not in the trail, the scope is wrong, not the trail. 4. For a scheduled report, wait for the first scheduled run rather than assuming. Confirm a new row appears in the history at the expected time with `is scheduled` set, and ask one recipient whether the mail arrived. A generated report that was never delivered looks successful from the console. 5. Confirm your own generation appears in the **Configuration trail** report, or in the operation log, as a `create` on **Report run**. ## Common errors | Symptom | Cause | Fix | | ---------------------------------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | The report is empty, or shorter than expected | The period falls partly or wholly outside the retention window | Check **System settings › Retention**. Data past the window is gone, and raising retention only helps from now on | | Status is success but the row count is 0 | Nothing happened in that period | Widen the period. This is not a failure, and the file is still valid evidence that nothing happened | | A scheduled report never arrives | The cron never fires, or the system cannot send e-mail | Check the entry against the history: rows but no mail is a mail problem, no rows is a cron problem | | A scheduled report arrives but covers the wrong span | **Window (days)** does not match the cron | Set the window to at least the interval between runs | | Recipients receive it but cannot open it | The format on the schedule is not the one they expected | Format is set per schedule, not once for the whole area | | A report you sent last month no longer matches | It was re-pulled instead of kept | The history stores no file. See the warning above | | Account inventory shows a stale `updated` date | Rotation is not reaching that account | Follow it up in [Rotation](/pam/administration/accounts/rotation). The report is correct, the rotation is not | | A wide report is slow or heavy | Long period across many assets | Narrow the period, or schedule it for a quiet window | ## Field reference ### Generate report | Field | What it does | Values | | ------------------- | ---------------------------- | -------------------------------------- | | Report type | Which generator runs | Ten operational, seven compliance | | Period, From and To | The window the report covers | Two dates, inside the retention window | | Format | Output file type | PDF, XLSX, CSV | ### New schedule | Field | What it does | Values | | ------------------- | ------------------------------------------------ | ---------------------------------------------------- | | Name | Identifies the schedule in the list | Free text | | Report type | Which generator runs | The same seventeen | | Format | Output file type | PDF, XLSX, CSV | | Window (days) | How far back each run reaches | Whole days. Default 7 | | Cron | When it runs | `minute hour day month weekday`. Default `0 6 * * 1` | | Recipients (e-mail) | Who receives it | One address per entry, Enter to add | | Active | Turns the schedule on or off without deleting it | On or off | ### History row | Field | What it holds | | ------------------- | ----------------------------------------------- | | Report type, Format | What was generated, and as what | | Status | `success`, or the failure with its error text | | Rows | How many detail rows the file carried | | Period | The window that run covered | | Date, Generated by | When, and by whom | | Is scheduled | Whether a schedule produced it, or a person did | ## Known limitations * **The report content is written in Portuguese**, whatever language the console is set to. Headers, summary labels, column names and the report titles themselves do not follow the interface language. A report for readers who do not read Portuguese has to be translated after it is generated. * **No scope filter at generation time**, as described under Generate now. ## Related pages * [Audit trail](/pam/administration/audit/audit-trail) — the records the reports are built from * [Compliance mappings](/pam/reference/compliance-mappings) — every control each package answers * [Session recordings](/pam/administration/audit/recordings) — the evidence a session report points at * [Managed accounts](/pam/administration/accounts/managed-accounts) — what the account inventory reports on * [Rotation](/pam/administration/accounts/rotation) — what the rotation report measures # Integrations | Page | What it covers | | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Syslog and SIEM](/pam/administration/integrations/syslog-and-siem) | Forward the audit trail continuously to an external collector — syslog over UDP, TCP or TLS, a text export, or Elasticsearch — so the records survive independently of the appliance. | | [Application-to-application access](/pam/administration/integrations/application-to-application) | Let tools and systems fetch credentials from the vault — scanners, pipelines, and containers — without ever storing the password outside it. | | [Vulnerability scanners](/pam/administration/integrations/vulnerability-scanners) | Give Tenable, Qualys or any other scanner the privileged credential an authenticated scan needs, fetched from the vault at scan time instead of stored inside the scanner. | | [AD Bridge for Linux hosts](/pam/administration/integrations/ad-bridge) | Join Linux hosts to Active Directory so directory users and groups become operating-system accounts, with UID mapping, sudo policy and keytab handling managed centrally. | # Syslog and SIEM Forward the audit trail continuously to an external collector — syslog over UDP, TCP or TLS, a text export, or Elasticsearch — so the records survive independently of the appliance. Log shipping sends the records the solution produces to a collector you already operate, as they happen. The point is independence: a trail that also lives in your SIEM survives the loss, compromise or reinstallation of the appliance, and it can be correlated with everything else your SOC watches. {% hint style="info" %} **Log shipping is not reporting.** Shipping is continuous, machine-to-machine, and goes to a collector. [Reports](/pam/administration/audit/reports) are periodic or on-demand extracts, formatted for people and delivered by e-mail. Both read the same underlying records — see [Audit trail](/pam/administration/audit/audit-trail) — and most environments want both. {% endhint %} ## What this is and when to use it Two mechanisms exist, they are configured in different places, and they carry different things. Confusing them is the usual reason a SIEM project stalls. | Mechanism | What it carries | Where it is configured | | --------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------- | | **Syslog forwarding** | The event records — logins, sessions, configuration changes, file transfers | In the appliance configuration file | | **Command storage backend** | The commands typed in terminal sessions, indexed for search | **System settings › Storage › Command storage** | Use syslog forwarding when the requirement is "our SIEM must hold the privileged-access trail". Use an Elasticsearch command-storage backend when the requirement is "searching the command history in the console is too slow" — by default commands live in the solution's own database, which is fine until the volume of terminal sessions grows. Available destinations for the trail: | Destination | Notes | | ------------------- | ------------------------------------------------------------------------------- | | **Syslog over UDP** | Default port 514. Fire and forget: no delivery guarantee | | **Syslog over TCP** | Default port 514. Connection-oriented | | **Syslog over TLS** | Default port 6514. Use this whenever the collector is not on a trusted segment | | **Text export** | A plain-text file, for collectors that read files or for an air-gapped hand-off | | **Elasticsearch** | Indexes command records for search, as a command-storage backend | ## Before you start * The collector's address and port, and a decision on the protocol. Prefer **TLS on 6514** unless the collector sits on a segment you already trust. * The collector must be reachable **from every node**. On a cluster, each node forwards its own records; a firewall rule that only covers one node produces a trail with holes in it. * The syslog facility your collector expects, so the records land in the right pipeline rather than in the default one. * A maintenance window. Enabling forwarding requires restarting the solution's services. {% hint style="warning" %} Syslog forwarding is **not configured from the console**. It is set in the appliance's configuration file, and the change takes effect only after the services restart. Open a support ticket so the change is made and recorded — do not edit a production appliance by hand without one. {% endhint %} ## Steps 1. **Choose the destination and protocol**, and open the path from every node to the collector on that port. 2. **Set the parameters** in the appliance configuration file, `/opt/datadike/config/config.txt`: ``` SYSLOG_ENABLE=true SYSLOG_ADDR=10.1.12.116:514 SYSLOG_FACILITY=local2 ``` `SYSLOG_ADDR` takes the collector's address and port together. `SYSLOG_FACILITY` must match what the collector's configuration expects. 3. **Restart the solution's services.** Nothing is forwarded until they come back. 4. **Repeat on every node** of a cluster. Each node ships its own records. 5. **Add a command-storage backend**, if command search is the goal, under **System settings › Storage › Command storage**. Leaving the list empty keeps commands in the local database. 6. **Build the collector side**: parsers, indices and dashboards. The records follow a common standard, so the usual collectors consume them without a custom parser. ## What you should see Records arrive as syslog lines carrying a record type and a JSON payload. The record type tells you which log the event came from: | Event | Record type | Payload highlights | | ------------- | ----------- | ----------------------------------------------------------------------------------------------------------------- | | Console login | `login_log` | The authentication backend, the source `ip`, the `username`, and a `status` object with the outcome | | File upload | `ftp_log` | The `account` used on the asset, the `filename`, a `value` of `upload`, the `remote_addr`, and the console `user` | | File download | `ftp_log` | The same fields, with a `value` of `download` | A single line looks like this, abbreviated: ``` Apr 19 15:25:11 10.1.14.125 datadike: login_log - { "backend": "Password", "ip": "10.1.10.35", "status": {"label": "successful", "value": true}, "username": "admin" } ``` The `datadike:` tag is what you filter on at the collector to isolate the solution's records. ## How to verify it worked Confirm arrival at the collector, not just that the configuration was saved. 1. **Force a known event.** Sign in to the console, or sign in with a deliberately wrong password. Both produce a `login_log` record within seconds. 2. **Search the collector for the `datadike:` tag** over the last few minutes and find that exact event. Match the `username`, the source `ip` and the `status` against what you just did — a record that arrives with the wrong fields is a parser problem, not a delivery problem. 3. **Exercise a second record type.** Upload a small file during a session and confirm an `ftp_log` record arrives with `"value": "upload"`. One record type working does not prove the rest are. 4. **Check every node.** On a cluster, sign in through each node and confirm each one's records reach the collector. This is the failure that goes unnoticed for months. 5. **If you added a command-storage backend**, run a terminal session, type a command, then search for that command in **Audit › Sessions › Keylogger**. The command must be found — if the backend is misconfigured, indexing fails silently and the console search comes back empty even though the session was recorded. {% hint style="warning" %} Test with a **failed** login as well as a successful one. A collector rule that only matches successes hides exactly the events you built the pipeline for. {% endhint %} ## Common errors | Symptom | Cause | Fix | | ------------------------------------------------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | Nothing arrives at the collector | The services were not restarted after the file was changed | Restart the solution's services; the configuration is read at start-up | | Nothing arrives, and the services were restarted | Wrong protocol or port, or the collector is unreachable from the nodes | Check against 514/UDP, 514/TCP and 6514/TLS, and test reachability from every node | | Records arrive from some sessions but not others | Only one node of a cluster is forwarding | Apply the configuration on every node | | Records arrive but land in the wrong pipeline | `SYSLOG_FACILITY` does not match the collector's configuration | Set the facility the collector expects, then restart | | Records arrive over UDP intermittently under load | UDP has no delivery guarantee | Move to TCP, or to TLS on 6514 | | The TLS destination refuses the connection | The collector's certificate is not trusted, or the port is wrong | Fix the trust chain and confirm the collector listens on 6514 | | Command search in the console is slow or empty | Commands are in the local database, or the Elasticsearch backend is misconfigured | Add or repair the command-storage backend and verify by searching for a command you just typed | | Events stop appearing for older dates | Retention has expired, independently of forwarding | Retention is set in **System settings › Retention**; the collector's own retention is separate and usually longer | ## Field reference ### Configuration keys | Key | Meaning | | ----------------- | ----------------------------------------------------------------------------------- | | `SYSLOG_ENABLE` | `true` turns forwarding on. Read at service start-up | | `SYSLOG_ADDR` | The collector, as `address:port` — for example `10.1.12.116:514` | | `SYSLOG_FACILITY` | The syslog facility, for example `local2`. Must match the collector's configuration | ### Default ports | Protocol | Port | | ---------- | ---- | | Syslog UDP | 514 | | Syslog TCP | 514 | | Syslog TLS | 6514 | ### Collectors known to consume the format without a custom parser | Category | Products | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | SIEM | Splunk, IBM QRadar, Microsoft Sentinel, Elastic Security, Google Security Operations, Securonix, LogRhythm, Graylog, Wazuh | | Log platforms and search | Elastic Stack (ELK), OpenSearch, Loki with Grafana | | Collectors and forwarders | rsyslog, syslog-ng, Fluentd, Fluent Bit | | Monitoring suites | SolarWinds, ManageEngine, Paessler PRTG, Nagios | The record format follows a common standard; anything that reads standard syslog or ingests JSON payloads will handle it, whether or not it appears above. ## Related pages * [Audit trail](/pam/administration/audit/audit-trail) — the records being forwarded, and where each one lives in the console * [Reports](/pam/administration/audit/reports) — the other delivery path: periodic extracts for people, not continuous shipping * [Session recordings](/pam/administration/audit/recordings) — stored separately from the event records * [Application-to-application access](/pam/administration/integrations/application-to-application) — the other integration that produces audit records worth watching in a SIEM # Application-to-application access Letting a tool fetch a credential from the vault instead of holding one of its own: registering the application, signing the request, and the trail every retrieval leaves. ## What this is and when to use it A2A lets **tools** rather than people fetch credentials from the vault. A scanner, a pipeline, a monitoring agent or an ITSM platform asks for the credential at the moment it needs it, uses it, and keeps nothing. The problem it solves is the credential nobody rotates: the password in a `config.yaml`, the key in a Jenkins variable, the service account pasted into a scanner years ago. Those credentials are invisible to the vault, so rotation never reaches them and no report can tell you who used them. {% hint style="info" %} **The direction matters, and it is often misunderstood.** The solution does not connect out to your tools. It **publishes an API that those tools call**. The integration work happens on the calling side, and nothing needs to be installed inside the solution. {% endhint %} ## Concepts | Term | What it means | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | **Integration application** | The identity a tool authenticates as. It is not a user, has no console access, and can do nothing but fetch the credentials in its scope | | **ID and secret** | The credential pair the application signs its requests with | | **Account scope** | The set of accounts this application may read. Anything outside it does not exist as far as this application is concerned | | **IP group** | The source addresses the application may call from | An application belongs to one organisation and reaches only that organisation's accounts. ## Before you start * An administrator role able to manage integration applications. * The accounts the tool will need, already managed in the vault. * The source addresses the tool will call from. ## Registering an application 1. Open **System settings › A2A** and create an application. 2. Give it a **name** that says which tool it is. This name appears in the audit trail, so "Tenable scanner, production" beats "app1". 3. Set the **accounts** it may read. Grant the narrowest set that lets the tool work. 4. Set the **IP group** to the addresses the tool calls from. 5. Save, then reveal the **secret**. Revealing it requires a second factor, and it is shown for the caller to copy. {% hint style="danger" %} **The IP group allows every address by default.** A new application is reachable from anywhere until you narrow it. Setting it is what turns a leaked secret from a breach into a failed call from the wrong network. {% endhint %} Requesting the secret again **replaces it**. Any client still holding the old value stops authenticating, so rotate on purpose, not to check what it was. ## Fetching a credential ``` GET /api/v1/accounts/integration-applications/account-secret/ ``` | Parameter | Use | | ------------ | ------------------------------------------------------ | | `account_id` | The account's UUID. The simplest form, used on its own | | `account` | The account name, when you do not hold the UUID | | `asset` | The asset name, to disambiguate an account name | | `asset_id` | The asset's UUID, same purpose | The request is signed with HTTP Signature, HMAC-SHA256, using the application's ID as `keyId` and its secret as the key. It also carries `X-Source: jms-pam`, which is what tells the solution to authenticate an application rather than a user's access key. ``` Authorization: Signature keyId="",algorithm="hmac-sha256", headers="(request-target) date",signature="" Date: Wed, 23 Sep 2026 20:44:35 GMT X-Source: jms-pam X-JMS-ORG: ``` A successful call answers with the secret and nothing else: ```json { "id": "", "secret": "" } ``` For the exact construction of the signing string, and the three details that most often break it, see [API](/pam/reference/api). ### Ready-made clients You do not have to implement the signature. The solution serves a working client and its documentation for six languages, under the application's **SDKs** tab: **Python, Java, Go, Node.js, PowerShell and curl**. Java, Go and PowerShell need no external library. ### Response codes | Code | Meaning | | ---- | ----------------------------------------------------------------------------------------------- | | 200 | The credential is in the body | | 400 | The parameters do not identify one account | | 401 | Signature rejected, application inactive, or the call came from an address outside the IP group | | 404 | No account matches, or the account is outside this application's scope | ## Integrating a tool that does not speak this API Platforms such as **Aranda**, **SOTI**, **Tenable** or **Qualys** do not natively know how to sign a request this way. Two patterns work, and both keep the credential out of the tool's configuration: * **A retrieval step before the job.** A short script, built from one of the supplied clients, fetches the credential and hands it to the tool at run time. This is the usual choice for pipelines and scan jobs. * **The platform's own extension mechanism**, where it has one, calling the endpoint above. {% hint style="warning" %} There is no drop-in connector for those platforms. The solution exposes a documented API and supplies reference clients; wiring it into a given platform is integration work on that platform's side. Plan for it rather than assuming a checkbox. {% endhint %} ## Every retrieval is recorded Each successful fetch writes an audit record carrying the application's name, the account and the asset it belongs to, the source address, and the time. It lands in the same trail as a person clicking *view* on a credential, which is what makes "who has read this credential, ever" a question with a complete answer. See [Audit trail](/pam/administration/audit/audit-trail) and [The credential vault](/pam/administration/accounts/vault). ## How to verify it worked 1. **Fetch one credential** with the supplied client and confirm the body carries the secret. 2. **Call again from an address outside the IP group** and confirm it is refused. An IP restriction nobody has tested is a setting, not a control. 3. **Ask for an account outside the application's scope** and confirm the 404. This is the check that proves the scope is real. 4. **Open the audit trail** and confirm both the successful and the refused calls are there. A retrieval that leaves no trace is not a retrieval, it is a leak. ## Common errors | Symptom | Cause | Fix | | ----------------------------------------------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | 401 with a correct-looking signature | The date header was formatted in the machine's own language, or the clock has drifted | Format the date in English, in GMT, and synchronise the host's clock | | 401 from a server but not from your workstation | The IP group does not include that server | Add the address | | The call authenticates as a user instead of the application | `X-Source: jms-pam` is missing | Add the header | | 404 for an account you can see in the console | It is outside the application's account scope, or in another organisation | Widen the scope, or send the right `X-JMS-ORG` | | Every client stopped working at once | The secret was revealed again, which replaces it | Distribute the new secret | | 200 but the secret comes back empty | Reading account secrets is disabled in the security settings | Review **System settings › Security** | ## Related pages * [API](/pam/reference/api) — how to sign a request, and the conventions every endpoint shares * [The credential vault](/pam/administration/accounts/vault) — what these calls read from * [Managed accounts](/pam/administration/accounts/managed-accounts) — the accounts an application's scope is built from * [Rotate credentials](/pam/administration/accounts/rotation) — why fetching beats storing * [Audit trail](/pam/administration/audit/audit-trail) — where every retrieval is recorded # Vulnerability scanners Give Tenable, Qualys or any other scanner the privileged credential an authenticated scan needs, fetched from the vault at scan time instead of stored inside the scanner. A vulnerability scanner sees very little from outside a host. Unauthenticated, it can only infer versions from what the network exposes; authenticated, it signs in and reads the installed packages, the patch level and the actual configuration. That is the difference between a plausible guess and a finding you can act on — and it is why every serious scan policy asks for a privileged credential. The problem is where that credential lives. A scanner configured the usual way holds a domain or root password in its own credential store, copied out of the vault, rotated by hand, and readable by anyone who administers the scanner. ## What this is and when to use it Instead of storing the password, the scanner **receives it at the moment of the scan**, fetched from the vault by an application identity created here. What that buys you: | | Credential stored in the scanner | Credential fetched from the vault | | ------------------------ | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------- | | Where the password lives | In the scanner, and in the vault | Only in the vault | | After a rotation | The scan fails until someone updates the scanner | The next fetch returns the new password | | Who can read it | Anyone with the scanner's administrative rights | Nobody. The value is never displayed | | Evidence of use | The scanner's own logs | Every fetch is in the audit trail, with the calling application, the account, the source IP and the time | ## How the credential reaches the scanner The solution publishes an API and the scanner calls it. There is **no drop-in connector** for Tenable or Qualys, so the fetch has to be wired in one of two ways: | Pattern | How it works | When to choose it | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | | **Pre-scan fetch** | A short script runs before the scan, retrieves the credential and hands it to the scanner or to the job that launches it | The usual choice. Works with any scanner and any scheduler | | **Platform extension** | The scanner's own scripting or plugin mechanism calls the endpoint directly | Where the platform supports it and you want no external step | The script is not work from scratch: the solution serves a working client for six languages under the application's **SDKs** tab, and the retrieval is a single call. See [Application-to-application access](/pam/administration/integrations/application-to-application) for the endpoint and the signature. {% hint style="warning" %} **Plan for integration work on the scanner's side.** The credential comes from a documented API with reference clients, not from a checkbox in the scanner. The effort is small and one-off, but it is not zero, and it belongs in the project plan. {% endhint %} ## Before you start * The assets to be scanned already registered, each with the **account** the scan will authenticate as. See [Managed accounts](/pam/administration/accounts/managed-accounts). * The solution reachable from the scanner over **HTTPS**, with a certificate the calling host trusts. * The **source IP addresses** of the scanner's engines. Not of your workstation, of the machines that will actually make the calls. * A decision on granularity: **one application per scanner**, so each has its own secret, scope, IP group and audit trail. Sharing one application across several tools destroys the attribution you built this for. ## Steps 1. **Create the application.** In **System settings › A2A**, create one named after the consumer, `tenable-scanner-prod` for example. 2. **Scope it to the accounts to be scanned.** Grant the accounts in that scanner's scan policy and nothing else. A scanner that can fetch every credential in the vault is a worse risk than the one you removed. 3. **Restrict the IP group** to the scanner's engines, as addresses or CIDR ranges. **It permits every address by default**, which defeats the point of a scoped secret. 4. **Reveal the secret** and place it in the scanner host's own secret store, or in the secret store of the scheduler that runs the fetch. 5. **Write the fetch step**, starting from the client in your language under the **SDKs** tab. 6. **Run the fetch by hand once**, from the engine that will perform the scan, and confirm it returns the credential. 7. **Then schedule the scan.** {% hint style="danger" %} Revealing the secret again **replaces it**. Every engine still holding the old value stops authenticating, so plan a rotation as a change, not as a way to look the value up. {% endhint %} {% hint style="warning" %} An application only reaches accounts **of its own organization**. Referring to an asset that belongs to another tenant resolves to nothing at scan time: the call reports the account as not found, and the scan quietly falls back to unauthenticated results. {% endhint %} ## How to verify it worked A scan that completes is not proof. An unauthenticated scan also completes, with far fewer findings and no error that says why. 1. **Check the API is answering.** From the scanner's own host: ```bash curl -s "https:///api/health/" ``` A healthy instance returns `"status": true`. A failure here is network, hostname or certificate, not the secret. 2. **Run the fetch step by hand** from the engine that will perform the scan, not from a workstation on a different address. 3. **Scan one asset, then read the audit trail.** Confirm a credential retrieval is recorded for that account, from the scanner's IP, at the time of the scan. A scan with results but no retrieval record is not using the vault, it is using a credential still stored in the scanner. 4. **Compare the finding count** against a previous unauthenticated scan of the same host. Authenticated scans report substantially more, and the check output states that authentication succeeded. If the numbers look like the old unauthenticated run, the login failed and the scanner fell back. 5. **Prove the IP restriction works.** Call from a different address and confirm it is refused. An allowlist you never tested is an allowlist you cannot rely on. 6. **Prove rotation is transparent.** [Rotate](/pam/administration/accounts/rotation) the account's password, then rescan without touching the scanner. It must still authenticate. ## Common errors | Symptom | Cause | Fix | | --------------------------------------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | The fetch fails with 401 | The signature, the clock, or the source address | Check the date format and the host clock, then confirm the engine's address is in the IP group | | It works from your workstation but not from the scanner | Only your address is in the IP group | Add the scanner engines' addresses. That is what the restriction is for | | 404 for an asset you can see in the console | The asset belongs to another organization | An application reaches only its own organization | | 404 for the right asset | The name does not match the registration exactly | Use the asset name and the account name exactly as registered | | Some hosts authenticate and others do not | Those accounts are outside the application's scope | Add them, or scan them with a separate application | | Everything worked, then every scan stopped authenticating | The secret was revealed again, which replaces it | Distribute the new secret to every engine | | The scan authenticates but finds almost nothing | The account is not privileged enough on the target for an authenticated check | Fix the account's privilege on the asset. The vault delivered the credential correctly | ## Field reference What to decide for each scanner, before creating anything: | Decision | Guidance | | --------------------- | -------------------------------------------------------------------------------------------------------------- | | **Application name** | One per scanner, named for the tool and the environment, `tenable-scanner-prod` | | **Account scope** | The accounts in that scanner's scan policy, and no others | | **IP group** | Every scanner engine that will call, as `/32` addresses or the engines' CIDR range | | **Account per asset** | A dedicated scan account with exactly the privilege the checks need, rotated like any other managed credential | Revocation is immediate: **deactivate** the application and the scanner stops receiving credentials, without anything changing on the target. ## Related pages * [Application-to-application access](/pam/administration/integrations/application-to-application) — the endpoint, the signature and the reference clients * [API](/pam/reference/api) — how to sign a request * [The credential vault](/pam/administration/accounts/vault) — where the scan credential lives * [Managed accounts](/pam/administration/accounts/managed-accounts) — registering the account the scan authenticates as * [Rotate credentials](/pam/administration/accounts/rotation) — why the scanner never needs updating after a rotation * [Audit trail](/pam/administration/audit/audit-trail) — where each credential fetch is recorded # AD Bridge for Linux hosts Join Linux hosts to Active Directory so directory users and groups become operating-system accounts, with UID mapping, sudo policy and keytab handling managed centrally. AD Bridge joins **Linux servers** to Active Directory or to a corporate LDAP directory, so that directory users and groups are recognized by the host as native operating-system accounts. The fleet stops carrying local account entries, unmanaged SSH keys and one-off credentials per machine. {% hint style="warning" %} **This is not the same thing as directory login to the console.** Authenticating *console users* against a directory is configured in [LDAP and Active Directory](/pam/administration/identities/ldap-and-ad) and installs nothing anywhere. AD Bridge is a property of the *target host*: an agent runs on the Linux server and turns directory identities into local accounts on it. The two features are configured separately and can be used independently. {% endhint %} ## What this is and when to use it In a mixed estate the Windows machines are usually already in the domain while the Linux fleet runs on scattered local accounts, with inconsistent policy from machine to machine. That widens the attack surface, makes timely revocation hard, and splits the audit trail. AD Bridge extends the directory identity down to the host: | Property | Effect | | --------------------------- | --------------------------------------------------------------------------------------------------- | | **One identity** | The directory `sAMAccountName` / `userPrincipalName` *is* the Linux login. No local aliases | | **Groups as authorization** | Directory group membership decides who reaches which hosts, and with which profile | | **Provisioning on demand** | The account and its groups are materialized on the host only when an authorized user first signs in | | **Central policy** | Access, sudo, shell and home-directory rules are defined once and pushed to the hosts | | **One audit trail** | Authentication, provisioning and privileged actions land in the same trail as every other event | Because authorization derives from directory groups, granting or revoking access across a whole Linux fleet is one operation in the directory, not a change on every machine. {% hint style="info" %} The directory stays the authoritative source of identity. The solution is the decision point and the audit point: every question of who may authenticate, on which host, under which policy, is evaluated centrally before it is applied to the operating system. {% endhint %} ## How the pieces fit Three planes, talking over authenticated and encrypted channels: | Plane | What it holds | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Directory** | Active Directory or LDAP: user and group objects, memberships, attributes, and whether an account is enabled or locked | | **Control plane** | The catalogue of joined Linux hosts, the authorized group sets per host or host group, the sudo rules, the provisioning parameters and the audit configuration | | **Host** | The AD Bridge agent: performs the join, resolves directory identities for the operating system, applies the policy it receives, and reports events back | The agent handles the join and the renewal of the machine account's trust, resolves users and groups into the host's name-service and authentication stack, applies the received policy locally, and reports authentication and provisioning events upward. {% hint style="warning" %} The agent stores **no cleartext user credential** on the host. Passwords are validated against the directory over Kerberos or LDAP. Offline cache, where enabled, keeps only protected verifiers, with a lifetime set by policy. {% endhint %} ## Before you start * **DNS.** The Linux host must resolve the domain's SRV records (`_ldap._tcp`, `_kerberos._tcp`) and the domain controller names. Inconsistent DNS is the single most common cause of a failed join. * **Time.** Kerberos requires low clock skew — typically under five minutes — between the host, the domain controller and the solution. Run NTP or chrony everywhere. * **Network.** The directory services (LDAP/LDAPS, Kerberos) must be reachable from the host, plus the authenticated channel from the agent to the solution. * **A join account.** A directory service account with delegated permission to create and manage machine accounts in the target OU. Keep it least privilege — scoped to the OU that holds the Linux servers, and nothing else. * **A supported distribution**, with the operating system's authentication stack available. * **The join credential in the vault.** It is custodied in the [credential vault](/pam/administration/accounts/vault), never in a file on the host. ## Steps 1. **Register the host.** The Linux server is added to [Inventory](/pam/administration/assets/inventory), by hand or through discovery, and gets its own identity and the AD Bridge agent. 2. **Decide the authorization model** before joining anything: which directory *groups* may authenticate on which hosts or host groups. Model by group, not by individual user — that is what makes granting and revoking scale. 3. **Join the host.** The agent requests the join credential; it is released from the vault just in time, scoped and time-limited to the join operation alone. The agent then locates a domain controller through DNS SRV, authenticates over Kerberos, and creates or updates the **machine account** in the designated OU. 4. **Trust is established.** A keytab for the machine account is generated and stored protected on the host, so Kerberos authentication no longer depends on a static password. 5. **Identity configuration is pushed.** The domain and realms, the UID/GID mapping scheme, the home-directory template and the default shell are sent to the host. 6. **Confirm and audit.** The agent confirms the join, and the event is written to the audit trail with the host, the OU, the machine account, the operator responsible and the timestamp. {% hint style="info" %} The join credential is never pinned on the host. After the join, trust rests on the machine account's keytab, whose password is rotated automatically according to the domain's and the solution's policy. {% endhint %} ### Leaving the domain Removal follows the same audited path in reverse: policy is revoked, the agent removes the local trust, and the machine account is disabled or deleted in the OU, with the whole event recorded. That is what keeps decommissioning free of orphan accounts. ## Provisioning on the host Authorized directory users and groups are materialized without touching the host by hand: * **Triggered by first sign-in.** When a directory user who belongs to an authorized group authenticates for the first time on a joined host, the account is created transparently. * **Home from a template.** The home directory is built from a policy-defined model — structure, skel, permissions — honouring the directory's POSIX attributes where they exist. * **Groups mirrored.** The relevant directory groups are reflected on the host under **the same names**, and they govern membership and privilege there. * **De-provisioning by policy.** Losing membership of an authorized group, or having access revoked centrally, ends the access. Inactive accounts can be archived or removed according to the retention you set. ## UID and GID mapping The identity must be the same on every host, and consistent with the directory: | Situation | What happens | | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | The directory publishes `uidNumber` / `gidNumber` | Those values are adopted directly | | No POSIX attributes are present | A deterministic algorithm derives the UID and GID from the object's immutable identifier (SID or GUID) | | Several domains or forests | Realms and trusts are handled so identities from different domains do not collide in the UID/GID space | {% hint style="warning" %} Deterministic derivation means **the same user gets the same UID on every host** — which is what makes shared filesystems such as NFS behave correctly. If you later add POSIX attributes to the directory for users who were already provisioned from derived values, the two schemes disagree and file ownership on shared storage stops matching. Decide which scheme you are using before rolling out the fleet, and prefer POSIX attributes in the directory wherever hosts share files. {% endhint %} ## Policy applied centrally Policies are defined once and propagated to the joined hosts: * **Access, by host and by host group.** Which directory groups may authenticate on which servers, optionally narrowed by time window and other contextual restrictions. * **Privilege elevation (sudo).** `sudo` rules per group and per host are administered centrally, in place of `sudoers` files edited machine by machine. * **GPO where it applies.** Where the environment publishes group policy with semantics that mean something on Linux — logon parameters, messages, compatible restrictions — AD Bridge interprets it and enforces it locally. * **Shell and home directory.** Default shell, skel and home-creation policy are made uniform by the distributed configuration. {% hint style="warning" %} **Two rules that disagree are resolved by specificity, not by order.** A rule written for a single host wins over a rule written for a host group, and the conflict is recorded for administrative review. Look for those records before concluding that a host "ignores" a policy. {% endhint %} {% hint style="info" %} A group policy directive with **no Linux equivalent is safely ignored and logged** — it does not half-apply and it produces no side effects. If you expected a Windows-only setting to take effect on a Linux host, the log is where you will find out that it was skipped. {% endhint %} ## What gets audited Everything mediated by AD Bridge feeds the [audit trail](/pam/administration/audit/audit-trail): | Family | Events | | --------------------- | ------------------------------------------------------------------------------------------------------------ | | **Authentication** | Successful and failed logon, origin, host, directory identity and method (Kerberos, password, offline cache) | | **Provisioning** | Creation, update and removal of accounts and groups, with the operator or policy responsible | | **Privileged action** | `sudo` and elevations, correlated to the real directory identity rather than masked behind a generic account | | **Trust** | Join and unjoin, keytab rotation and changes to trust | Records are immutable, timestamped and correlatable with the rest of the trail, so "who accessed what, when, from where, and under which authorization" can be reconstructed end to end. ## How it works with the rest of the solution * **Vault.** Join credentials and keytabs are custodied and rotated by the [vault](/pam/administration/accounts/vault), delivered just in time, never left in configuration files. * **Session recording.** Interactive SSH and console sessions opened by directory identities on these hosts can be mediated and recorded, indexed by command and by user. * **RBAC.** [Roles](/pam/administration/identities/roles) decide who administers the integration, who approves privileged access and who may read the audit — keeping operator, approver and auditor separate. * **Approval and time-limited access.** Elevated access on Linux hosts can require approval and expire, in line with the [just-in-time](/pam/administration/access/just-in-time) policies. ## How to verify it worked Do not stop at "the join reported success". Check the things that actually break later: 1. **The join is in the trail.** Confirm the join event, with the host, the OU, the machine account and the operator. Then confirm in the directory that the machine account exists in the OU you intended — not in the default computers container. 2. **An authorized identity provisions on first sign-in.** Sign in to the host with a directory user who belongs to an authorized group. The account must be created, the home directory must exist from the template, and `id ` must return the directory's groups. 3. **The UID is the same everywhere.** Run `id ` on a **second** joined host and compare. Different UIDs on two hosts mean the two are not using the same mapping scheme, and shared storage will show the wrong owners. 4. **`sudo` is attributed to the real person.** Run a privileged command and confirm the audit record names the directory identity, not a generic account. This is the whole point of the integration. 5. **Revocation actually revokes.** Remove the test user from the authorized group in the directory and confirm the next sign-in is refused. 6. **After an unjoin**, confirm the machine account is disabled or deleted in the OU and that no orphan accounts remain on the host. ## Common errors | Symptom | Cause | Fix | | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- | | The join fails while locating the domain | The host cannot resolve the domain's SRV records | Fix DNS on the host and verify `_ldap._tcp` and `_kerberos._tcp` resolve before retrying | | The join reaches the controller and then fails on Kerberos | Clock skew above the allowed window | Enable NTP or chrony on the host, the controller and the solution, then retry | | The join fails when creating the machine account | The join account lacks delegated rights in the target OU | Delegate machine-account creation on that OU to the join account, keeping it least privilege | | A directory user cannot sign in on a joined host | The user is in no group authorized for that host | Add the group to the host's authorization, not the individual user | | The same user has different UIDs on two hosts | One host reads POSIX attributes from the directory and the other derived them, or the attributes were added after provisioning | Settle on one scheme; where hosts share files, publish POSIX attributes in the directory | | A group policy setting has no effect on Linux | The directive has no Linux equivalent and was safely ignored | Check the log for the skipped directive; enforce the equivalent through the central Linux policy instead | | One host behaves differently from the rest of its group | A host-specific rule overrides the host-group rule | Read the recorded conflict, then remove or correct the more specific rule | | Authentication keeps working while the directory is down, or stops | Offline cache is enabled or disabled, with a policy-defined lifetime | Decide the offline behaviour by policy rather than discovering it during an outage | | A decommissioned host still has an account in the directory | The host was wiped instead of being unjoined | Unjoin through the solution so the machine account and the policy are removed and recorded | ## Field reference ### POSIX attributes honoured from the directory | Attribute | Used for | | ------------------- | ----------------------------------------- | | `uidNumber` | The account's numeric user ID on the host | | `gidNumber` | The account's primary numeric group ID | | `loginShell` | The login shell | | `unixHomeDirectory` | The home directory path | Publishing them is not a condition of the integration. Where they are absent, UID and GID are derived deterministically from the object's SID or GUID. ### Practices worth adopting | Practice | Why | | ----------------------------------------------------------- | ---------------------------------------------------------------------- | | Dedicate an OU to the Linux servers and delegate only to it | Keeps the join account least privilege | | Standardize NTP and DNS before joining the fleet | The two causes of nearly every failed join | | Publish POSIX attributes where hosts share files | Removes any dependence on derived UIDs across NFS | | Authorize by group, never by user | Grant and revoke stay one operation for the whole fleet | | Set recording and audit retention up front | A question asked outside the retention window cannot be answered later | ## Related pages * [LDAP and Active Directory](/pam/administration/identities/ldap-and-ad) — the other directory integration: authenticating *console users*, with nothing installed * [Discovery of accounts](/pam/administration/accounts/discovery-of-accounts) — treating directory accounts as managed credentials * [The credential vault](/pam/administration/accounts/vault) — where the join credential and the keytabs live * [Audit trail](/pam/administration/audit/audit-trail) — where authentication, provisioning and `sudo` events land * [Users and groups](/pam/administration/identities/users-and-groups) — how group membership drives authorization # Deploy and operate | Page | What it covers | | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [System requirements](/pam/deploy-operate/requirements) | Deployment models, machine sizing, storage planning and platform dependencies for a DataDike PAM instance, with the figures DataDike publishes and the gaps you must confirm before you buy hard | | [Network and connectivity requirements](/pam/deploy-operate/network-requirements) | The connectivity the solution itself needs — who reaches the console and on which ports, what the solution originates outbound, how to publish it safely, and why it needs no internet access of its own. | | [Install a single node](/pam/deploy-operate/install-single-node) | The documented path for bringing up one instance from the appliance image — console setup, DNS, first login, licence — and the parts of the procedure that only DataDike holds. | | [Install a high-availability cluster](/pam/deploy-operate/install-cluster) | What a high-availability deployment is made of, how it differs from a single node, the decisions to settle before the build, and how to prove the cluster actually tolerates losing a node. | | [Certificates and HTTPS](/pam/deploy-operate/certificates) | Serving the console over HTTPS: the name the certificate has to match, the Site URL setting that has to agree with it, and what breaks quietly when the two disagree. | | [Upgrade](/pam/deploy-operate/upgrade) | What is established about upgrading the solution, the preparation you own before one, the version-specific traps on record, and how to verify an upgrade afterwards. | | [Availability, SLA and updates](/pam/deploy-operate/availability-and-sla) | Availability levels, SLA, redundancy and the update and support model, for the SaaS and on-premises delivery modes. | | [Back up and restore](/pam/deploy-operate/backup-and-restore) | Backing up the installation — database, configuration and recordings — where each of those actually lives, and the test restore that turns a backup into something you can rely on. | | [Monitoring and health](/pam/deploy-operate/monitoring) | How to tell whether the installation is healthy: the health endpoint an external monitor should poll, the console screens that show component and task state, and the alerts worth subscribing to. | # System requirements Deployment models, machine sizing, storage planning and platform dependencies for a DataDike PAM instance, with the figures DataDike publishes and the gaps you must confirm before you buy hard ## What this page covers What one instance of the solution needs in order to run: where it can be deployed, how large the machine has to be, how much disk the recordings will consume, and which platform services it depends on. For the connectivity it needs, see [Network and connectivity requirements](/pam/deploy-operate/network-requirements). For the ports used to reach *assets*, see [Ports and protocols](/pam/reference/ports). {% hint style="warning" %} The sizing figures below are the ones published in DataDike's datasheet. They are a starting point, not a capacity model: storage in particular depends on your own retention policy and session mix. Confirm the sizing for your deployment with DataDike before you commit hardware, and confirm it against the version you are actually deploying. {% endhint %} ## Deployment models The solution runs on standard **x86\_64** infrastructure, on physical servers or virtual machines. | Model | What it means | | ----------------- | ------------------------------------------------- | | **On-premises** | Deployed in the customer's own data centre | | **Private cloud** | VMware, Hyper-V, KVM or OpenStack | | **Public cloud** | AWS, Azure, Google Cloud or Oracle Cloud | | **Hybrid** | Central instance on-premises, connectors in cloud | The DataDike OS documentation adds **Nutanix** and **KVM/Proxmox** to the list of hypervisors, and recommends installing directly on bare metal, without virtualisation, for best performance. ## Machine sizing ### Minimum — labs, testing and proof of concept | Resource | Minimum | | ---------------- | --------------------------------------------------------- | | CPU | 4 vCPU | | Memory | 8 GB RAM | | Storage | 100 GB SSD | | Network | 1 Gbps | | Architecture | x86\_64 | | Operating system | Oracle Linux, Ubuntu Server, Red Hat, Debian, DataDike OS | ### Recommended for production | Resource | Recommended | | --------- | ------------- | | CPU | 8 vCPU | | Memory | 8 – 16 GB RAM | | Storage | 500 GB SSD | | Disk type | SSD or NVMe | | Network | 1 Gbps | ### What drives those numbers up Storage, above all. The datasheet names four factors: * the retention period for **session recordings**; * the volume of **audit logs**; * the number of **managed assets**; * the number of **concurrent sessions**. ## Storage for session recordings Recordings are compressed and optimised before they are stored, in local storage and in external object storage alike. The datasheet publishes this average: | Sessions per day | Storage per month | | ---------------- | ----------------- | | 100 | \~50 GB | | 500 | \~250 GB | | 1000 | \~500 GB | {% hint style="warning" %} The source does not state the session length, protocol mix or compression setting behind those figures, and graphical sessions (RDP and VNC) consume far more space than terminal sessions. Treat the table as an order of magnitude only, and measure your own consumption over the first weeks of operation. {% endhint %} Two operational points that follow from it: * The recording backend installed by default (**default**, type **Server**) is local disk on the node. It has no redundancy, it consumes the node's own disk, and it does not scale — move to external object storage for production. * The retention setting in the console controls the **metadata in the database**, not the files. The real lifecycle of recording files is configured in the bucket or container that holds them. ## Platform dependencies | Dependency | What the sources say | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Database | Integrated into the appliance, internal to the solution. Managed database services (Amazon RDS, Cloud SQL) appear in the datasheet as optional integrable services | | Redis | Present in a deployed instance — the health endpoint reports its status and response time alongside the database's | | Object storage for recordings | S3, Ceph, Swift, OSS, Azure, OBS, COS, SFTP, local (**Server**) or discard (**Null**) | | Command storage | Stored in the solution's own database by default; an external index such as Elasticsearch can be configured instead | | Time source | NTP, or the host operating system's own date and time service | {% hint style="danger" %} The clock is not a detail. TOTP codes are validated to the second, so a node whose clock has drifted rejects every one-time password with *OTP code invalid, or server time error* — an outage that looks like an authentication bug. Synchronise the clock and set the correct timezone before you hand the instance over. {% endhint %} ## Browsers Console access is supported on Mozilla Firefox, Google Chrome, Microsoft Edge, Opera and Safari. ## Public cloud instance examples These are the example shapes the datasheet publishes for each provider. They are examples, not a support matrix. | | AWS | Azure | GCP | OCI | | -------------- | ----------------------------- | ------------------- | ------------------------------ | ----------------- | | Instance | EC2 t3.xlarge or m6i.xlarge | D4s\_v5 or D8s\_v5 | n2-standard-4 or n2-standard-8 | VM.Standard3.Flex | | CPU | 4–8 vCPU | 4–8 vCPU | 4–8 vCPU | 2–4 OCPU | | Memory | 8–16 GB | 8–16 GB | 8–16 GB | 8–16 GB | | Storage | EBS SSD (gp3) | Premium SSD | Persistent SSD | Block Volume SSD | | Load balancing | AWS Application Load Balancer | Azure Load Balancer | Google Cloud Load Balancer | OCI Load Balancer | Services the datasheet lists as optionally integrable, per provider: | Provider | Services | | -------- | --------------------------------------------------- | | AWS | Amazon RDS, Amazon S3, AWS IAM, AWS Secrets Manager | | Azure | Azure AD, Azure Key Vault, Azure Storage | | GCP | Google IAM, Cloud Storage, Cloud SQL | | OCI | OCI Object Storage, OCI Vault | ## Scaling and high availability The solution scales horizontally. The datasheet names four strategies: multiple nodes, distributed session proxies, an external database, and dedicated storage for recordings. High availability is offered as **active-active**, **active-passive** or a **DR replica** cluster: several nodes behind a virtual address (keepalived), with data replicated between the nodes. Access survives the loss of a node, and the session load is distributed or redistributed across the remaining ones. [Availability, SLA and updates](/pam/deploy-operate/availability-and-sla) states design objectives of **RTO ≤ 1 hour** and **RPO ≤ 15 minutes** for the active/active architecture, and redundancy of the vault, session-brokering and administration console components so that none of them is a single point of failure. See [Install a high-availability cluster](/pam/deploy-operate/install-cluster) for what a cluster deployment involves. ## How to check a running instance against these requirements * Poll the unauthenticated health endpoint `/api/health/`. It returns JSON with `status`, `db_status`, `db_time`, `redis_status`, `redis_time` and `time` — which proves the database and Redis are reachable, not merely that the web server answered. This is the right thing for an external monitor to watch. * Open **System settings › Components** and read the **Stat** column, which shows CPU and memory use per component, and **Load status**, which reads **Normal**, **High load** or **Offline**. Components sitting at **High load** are the signal to add capacity, either by growing the node or by adding instances of that component type. * Check the recording backend before disk pressure finds you: an instance left on the local **default** backend fills the node's own disk. ## Related pages * [Network and connectivity requirements](/pam/deploy-operate/network-requirements) * [Install a single node](/pam/deploy-operate/install-single-node) * [Install a high-availability cluster](/pam/deploy-operate/install-cluster) * [Ports and protocols](/pam/reference/ports) * [Core concepts](/pam/get-started/core-concepts) # Network and connectivity requirements The connectivity the solution itself needs — who reaches the console and on which ports, what the solution originates outbound, how to publish it safely, and why it needs no internet access of its own ## What this page covers The firewall rules the **solution** needs: what must reach it, what it must reach, and in which direction. It is not the list of ports used to reach *assets*. That list is per platform and lives in [Ports and protocols](/pam/reference/ports) — write your asset-side firewall requests from there, and use this page for the solution's own rules. {% hint style="danger" %} Once deployed, the solution itself requires **no internet access at all**. Block it. Deploy it in a **segmented, segregated network**. If your network is flat, the solution cannot deliver what it is for — regularise the network design before you deploy it, not after. {% endhint %} ## Traffic the solution needs | Source | Destination | Service | Port | Why | | ---------------------- | --------------- | ------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | Console users | The solution | HTTP | 80 | Console access over HTTP | | Console users | The solution | HTTPS | 443 | Console access over HTTPS | | Console users | The solution | SSH | 2222 | Command-line access to the solution | | The solution | Web-access host | SSH | 22 | The solution connects to the host to deploy the agent and the control mechanism | | The solution | Web-access host | RDP | 3389 | As above, where the host is reached over RDP | | Web-access host | The solution | HTTPS | 443 | The host authenticates back to the solution | | Web-access host | The solution | HTTP | 80 | As above, over HTTP | | Web-access host | Internet | Depends on the sites published | Depends | Only the URLs actually published in the solution — HTTP, HTTPS, or a non-standard port such as 8080. Enumerate the published URLs and open exactly those | | Your monitoring server | The solution | Zabbix agent | 10050 | Zabbix agent v1, where you monitor the node with Zabbix | | The solution | Windows asset | WinRM | 5985 | Remote execution of automations (account collection, credential rotation) | {% hint style="info" %} Two notes on that table. **HTTP and HTTPS are both listed.** Whether you actually need port 80 depends on whether the instance is meant to answer over HTTP at all. Confirm before you open it — an instance reached only over HTTPS does not need it. **The WinRM rule belongs to the solution, not to your monitoring server.** The source table attributes it to the Zabbix server, which appears to be a copy-paste of the row above it: automations are executed by the solution's own task service. See [Ports used by automations](/pam/reference/ports#ports-used-by-automations). {% endhint %} ## The web-access host is the exception to "no internet" Two different machines, and confusing them produces either a broken feature or an unnecessary hole in the perimeter: * **The solution** needs no internet access. Block it outbound. * **The web-access host** — the host that runs published web sessions — needs outbound access to the sites you publish, and nothing else. Open it per URL. ## Publishing the console outside the perimeter If users must reach the console from outside, publish it through **NAT behind a WAF**, over **port 443 (HTTPS)** only. From that single entry point the user reaches every internal asset — RDP, SSH, Telnet, VNC, databases — with no direct connectivity between the user's device and the protected assets. {% hint style="warning" %} Do not publish the console to the internet without a firewall and a WAF in front of it. If that protection is not in place, allow access only over a controlled VPN instead. {% endhint %} ## Networks the solution cannot route to Two mechanisms, in opposite directions. An asset uses one or the other and never both — the asset record forces the choice. | | Direction | What the network must allow | | ------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Proxy](/pam/administration/connectivity/proxy) | Solution → asset network | A route from the solution to the proxy host, with the SSH port open in that direction. The proxy needs a stored credential, and must itself be able to see the assets it serves | | [Broker](/pam/administration/connectivity/broker) | Asset network → broker | Outbound **443/tcp** from the remote environment to the broker. No inbound port is opened in the remote network at all | {% hint style="danger" %} A broker must be reached by a **DNS name, never a bare IP address**. The address is written into the certificates and into the enrolment tokens, and cannot be changed afterwards without reinstalling the broker. An IP literal only ever works for one network path: behind NAT, the LAN and the internet do not see the same address. {% endhint %} Gateways and connectors communicate in **one direction only**, chosen per environment: allow outbound traffic or allow inbound traffic, not both. RDP and SSH traffic can be encapsulated in HTTPS through the secure tunnel. See [Gateways](/pam/administration/connectivity/gateways). ## Traffic the solution originates | Destination | What for | Port | | ----------------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Assets | User sessions and automations | Per platform and per asset — see [Ports and protocols](/pam/reference/ports) | | Your syslog or SIEM collector | Audit event forwarding | Set in the appliance configuration file `/opt/datadike/config/config.txt`, as `SYSLOG_ADDR=:` with `SYSLOG_FACILITY`. The documented example uses port 514 and facility `local2`. Changing it requires a support ticket and a restart of the services | | Your mail server | Backup delivery, alerts and approval workflows | Not documented — take it from your mail server's configuration | | Your directory | LDAP / Active Directory authentication and account import | Not documented — take it from your directory. For LDAPS, the certificate files are loaded onto the appliance and the service restarted. See [LDAP and Active Directory](/pam/administration/identities/ldap-and-ad) | ## Monitoring Point your monitor at the unauthenticated health endpoint `/api/health/`. It returns JSON with `status`, `db_status`, `db_time`, `redis_status`, `redis_time` and `time`, so a successful poll proves the database and Redis are reachable — not merely that the web server is answering. In a cluster, poll the virtual address and each node directly. ## Clusters A cluster is fronted by a **single virtual address**, and clients are pointed at that address rather than at any individual node. Each node also answers directly on its own address, which is what makes per-node monitoring possible — so your monitoring source needs to reach each node, not only the virtual address. The ports used **between** cluster nodes for replication come from DataDike. Get them before you place the nodes in different network segments. ## Common errors | Symptom | Cause | Fix | | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | The console does not answer on its hostname during initial setup | The DNS record does not exist yet | Add a temporary entry to the hosts file of your own workstation to get through setup, then create the record in your private DNS — and in public DNS too if you are publishing through NAT | | The firewall rule is open but the session still fails | The rule was written from the platform's default port, while the asset uses a different effective port | Check the port on the asset record. See [Ports and protocols](/pam/reference/ports) | | Reverse access through a broker stops working after a network change, or never worked from one side | The broker was enrolled against an IP literal | The broker address must be a DNS name. Changing it means reinstalling the broker | | SSH to the solution on 2222 is refused | The port is closed, or the containers are not running on the node | Test reachability on port 2222 from the client network, then check the state of the containers on the node | | Every one-time password is rejected | The node's clock has drifted; TOTP is validated to the second | Synchronise the clock over NTP and set the correct timezone | ## Related pages * [System requirements](/pam/deploy-operate/requirements) * [Ports and protocols](/pam/reference/ports) * [Broker](/pam/administration/connectivity/broker) * [Gateways](/pam/administration/connectivity/gateways) * [Proxy](/pam/administration/connectivity/proxy) # Install a single node The documented path for bringing up one instance from the appliance image — console setup, DNS, first login, licence — and the parts of the procedure that only DataDike holds. {% hint style="warning" %} **Validate this procedure against the version you are deploying.** Installation procedure changes between releases, and the sources this page is built from do not state which version they were written for. Before you start, confirm the current procedure and the correct appliance image with DataDike. The image itself, the licence file and the low-level installation steps are maintained by DataDike and are not reproduced here. Nothing on this page is a substitute for the release-specific installation notes. {% endhint %} ## What this is and when to use it The single-node path: one machine, running everything. It is the right shape for a lab, a proof of concept, or a production environment that does not need to survive the loss of the node. If access must survive a node failure, deploy a cluster instead — see [Install a high-availability cluster](/pam/deploy-operate/install-cluster). The deployment is containerised and fronted by nginx. It is delivered as an appliance image that you import into your hypervisor or cloud, then configure from a console menu on first boot. ## Before you start * A machine that meets the [system requirements](/pam/deploy-operate/requirements), with the disk sized for your recording retention rather than the minimum figure. * The firewall rules from [Network and connectivity requirements](/pam/deploy-operate/network-requirements), agreed before the machine is deployed rather than after. * The appliance image and the licence file, from DataDike. * A DNS name for the instance, and the ability to create the record in your private DNS. A wildcard or subdomain certificate if you are terminating HTTPS on the instance. * The implementation support contact. Two of the steps below — installing the certificate and any change to the appliance configuration file — are performed on the appliance's command line by that team. ## Steps 1. **Import the appliance image** into the hypervisor or cloud and start it. 2. **Configure the machine from the first-boot console.** Sign in to the console with the documented appliance user (see [Documented defaults](#documented-defaults) below). The menu covers network configuration, the hostname, system information, and reboot and shutdown. 3. **Set the date, time and timezone correctly** before going any further. A drifted clock breaks one-time passwords and is easily mistaken for an authentication fault. 4. **Reach the console by name, temporarily.** Until the DNS record exists, add an entry mapping the instance's address to its hostname in the hosts file of your own workstation — on Windows, `C:\Windows\System32\drivers\etc\hosts`. This is a setup aid for your machine only, not a deployment step. 5. **Sign in to the console** at `https://` with the documented default administrator account, and change its password immediately. 6. **Import the licence.** Every function of the platform stays disabled until the licence is imported, so do this before you try anything else and conclude the build is broken. 7. **Install the HTTPS certificate.** This is performed by the implementation support team on the appliance's command line, with your wildcard or subdomain certificate. 8. **Create the definitive DNS records** — in your private DNS, and also in public DNS if you are publishing the console through NAT or DNAT. Then remove the temporary hosts entry from your workstation. 9. **Validate the firewall rules** against [Network and connectivity requirements](/pam/deploy-operate/network-requirements), from a client that sits where real users will sit. 10. **Connect your authentication sources** and set the inactivity and auto-disable thresholds for accounts. 11. **Register the assets** to be protected — manually, by spreadsheet import, or by discovery and synchronisation. 12. **Register the accounts** to be managed on those assets. 13. **Configure the mail server.** It carries backup delivery, alerts and approval workflows, so several later features silently do nothing without it. 14. **Set up the vault backup policy and automation**, and set the retention periods for logs and session records. 15. **Turn off component registration.** Once every component has registered, clear **Registration** in **System settings › Components › Basic**. While it is enabled, any component that knows the address of the instance can register itself. Re-enable it only for as long as it takes to add a new component. ## What you should see The console answers over HTTPS on its DNS name with a valid certificate. After the licence import, the menu areas that were inert become usable. **System settings › Components** lists the platform's own microservices — the core API, the task service, and the terminal, graphical, database and virtual application connectors — each with a **Load status** of **Normal** and a **Remote address** pointing at the node. ## How to verify it worked Four checks, in this order. Each one proves something the previous one does not. 1. **The platform's own dependencies.** Request `/api/health/` — no authentication needed. The JSON it returns carries `status`, `db_status`, `db_time`, `redis_status`, `redis_time` and `time`. A healthy response proves the database and Redis are reachable, which a plain "the login page loads" does not. 2. **The components.** On **System settings › Components**, every component shows **Normal**. Anything reading **Offline** is a service that did not come up, and the connectors are the ones users will notice first. 3. **The clock and the second factor.** Enrol one account with a one-time password and sign in with it. If the code is rejected, the clock is wrong, not the account. 4. **A real session, end to end.** Connect to one registered asset with one managed account, then find that session in the audit trail with its recording attached and playable. This is the only check that exercises the whole path — authentication, authorisation, credential injection, the connector, and the recording store. ## Common errors | Symptom | Cause | Fix | | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | The console loads but most features are unavailable | The licence has not been imported | Import the licence. All functions stay disabled until it is present | | The hostname does not resolve during setup | The DNS record has not been created yet | Add the temporary hosts entry on your own workstation, then create the definitive record in your private DNS | | *OTP code invalid, or server time error* on every login | The node's clock has drifted; TOTP is validated to the second | Synchronise the clock over NTP and set the correct timezone | | A component shows **Offline** in the Components list | The service did not start on the node where it is installed | Check that service on that node. An offline core API takes the whole platform down; an offline connector removes one session type | | The node's disk fills within weeks | Recordings are still going to the local **default** backend, which has no redundancy and does not scale | Configure external object storage and make it the default backend | | Sessions from a client network fail while they work from the console network | A firewall rule was validated from the wrong place | Re-test from a client that sits where real users sit | ## Documented defaults These are the defaults the sources document. Treat all of them as things to change or confirm, not as configuration to keep. | Item | Documented default | Note | | ----------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------- | | Appliance console user | `client` / `client@client` | Change it as part of the build | | Console administrator | `admin` / `datadike` | Change it at first login, before the instance is reachable by anyone else | | Command-line access to the solution | SSH on port 2222 | Not port 22 — that port belongs to the assets | | Recording backend | **default**, type **Server** (local disk) | Not suitable for production | | Component registration | Enabled | Disable it once the build is complete | | Licence grace period | 7 days after expiry | Time to load the new licence, not a licence-free period | {% hint style="danger" %} The two default credentials above are published in DataDike's documentation, which means an attacker has them too. Change both before the instance is reachable from anywhere but your own workstation. {% endhint %} ## Related pages * [System requirements](/pam/deploy-operate/requirements) * [Network and connectivity requirements](/pam/deploy-operate/network-requirements) * [Install a high-availability cluster](/pam/deploy-operate/install-cluster) * [LDAP and Active Directory](/pam/administration/identities/ldap-and-ad) * [Core concepts](/pam/get-started/core-concepts) # Install a high-availability cluster What a high-availability deployment is made of, how it differs from a single node, the decisions to settle before the build, and how to prove the cluster actually tolerates losing a node. {% hint style="warning" %} **Validate this procedure against the version you are deploying.** Installation procedure changes between releases, and the sources this page is built from do not state which version they were written for. **The step-by-step cluster build is performed with the DataDike implementation team.** Node provisioning, database and Redis replication, shared recording storage, and the virtual-address configuration are all release-specific and are performed with the implementation team. What follows is what a cluster is composed of, what you must decide before the build, and how to verify the result — not a procedure to follow unaided. {% endhint %} ## What this is and when to use it A cluster is several nodes behind one virtual address, with the data replicated between them, so that the loss of a node does not take privileged access with it. Choose it when an outage of the platform means an outage of your ability to administer everything else. Everything on [Install a single node](/pam/deploy-operate/install-single-node) still applies — licence, DNS, certificate, authentication sources, retention. This page covers only what changes. ## How a cluster differs from a single node | | Single node | Cluster | | ------------------ | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | Client entry point | The node's own address | A **single virtual address** (keepalived). Point users, DNS and integrations at the virtual address, never at a node | | Node addresses | The one address | Each node also answers directly on its own address, which is what makes per-node monitoring possible | | Data | Local to the node | Replicated between the nodes | | Session load | On the node | Distributed across the nodes, and redistributed when one is lost | | Recording storage | Local disk is the installed default | Local disk leaves each recording on whichever node produced it. External object storage is effectively mandatory | | Components | Register once | Each node's components register themselves, and appear in the console with that node's own address | Three topologies are offered: **active-active**, **active-passive**, and a **DR replica** cluster. The availability documentation states design objectives of **RTO ≤ 1 hour** and **RPO ≤ 15 minutes** for the active/active architecture, and redundancy of the vault, session-brokering and administration console components so that none of them is a single point of failure. ## Before you start * **Sizing per node.** The published figures cover one instance; see [System requirements](/pam/deploy-operate/requirements). Confirm with DataDike whether every node carries the same specification and what the shared storage tier needs. * **The virtual address**, and the DNS name that points at it. The name your users and integrations use must resolve to the virtual address, not to a node. * **External object storage for recordings**, configured as the default backend from day one. Retrofitting it later leaves recordings stranded on individual nodes. * **Firewall rules**, including the ports used between nodes for replication. Get them from DataDike before you place nodes in different segments. See [Network and connectivity requirements](/pam/deploy-operate/network-requirements). * **The additional licensing** the availability documentation says on-premises high availability requires "according to the sizing" — it gives database and Windows RDS licensing and HA licences as examples, without a definitive list. Settle it commercially before the build. ## How the cluster is composed The platform is a set of microservices that **register themselves** with the core once they are installed and configured, which is how a cluster is assembled: each node's terminal, graphical, database and virtual application connectors, its task service and its recording services appear in the console as separate registered components, each showing the address of the node it runs on. {% hint style="warning" %} Registration is enabled by default, and while it is on, **any component that knows the address of the platform can register itself**. Once every node's components are present, clear **Registration** in **System settings › Components › Basic**, and re-enable it only for as long as it takes to add a node or a connector. {% endhint %} Reverse access through a [broker](/pam/administration/connectivity/broker) is redundant by design: the component that dials the broker runs as **one instance per cluster node**, each with its own identity, automatic enrolment and autonomous recovery. Losing a platform node does not interrupt reverse access, and neither does losing a broker node — the remaining ones keep serving. ## If the platform is delivered as SaaS The vendor-hosted modality is offered with a **redundant local connector** in your environment, so that access keeps working transparently if the link to the cloud drops. Synchronisation between the components of the two sites is automatic and in real time: if one site's components become unavailable, the other site takes over the services without data loss. Connections are **one-directional** — from your environment towards the vendor cloud, never the reverse. ## What you should see The virtual address answers, and so does each node on its own address. **System settings › Components** lists the components of every node, each with its own **Remote address** and a **Load status** of **Normal**. A node that never registered is visible as an absence in that list, which is easier to miss than a failure — count the nodes. ## How to verify it worked A cluster that has never been failed over is not a verified cluster. 1. **Poll `/api/health/` on the virtual address**, then on **each node directly**. The endpoint needs no authentication and returns `status`, `db_status`, `db_time`, `redis_status`, `redis_time` and `time` — so it proves that node's database and Redis access, not just that nginx answered. Leave the per-node polls in your monitoring permanently; a cluster hides a single sick node behind the virtual address, and this is what exposes it. 2. **Count the components.** Every node's connectors present in **System settings › Components**, all **Normal**, each with the expected **Remote address**. 3. **Confirm recordings are not node-local.** Open a session on one node, then play its recording back through the virtual address until you have landed on a different node. If playback depends on which node answers, the recordings are still on local disk. 4. **Fail a node on purpose**, in a maintenance window, with DataDike's guidance. The virtual address must still answer, a new session must still connect, and the audit trail must still show it. Then bring the node back and confirm it rejoins — the components list is where you see it return. 5. **Check what happened to the sessions that were in progress** during that test. The sources state that access remains available and that the session load is redistributed; they do not state that sessions already open survive a node failure. Measure it in your own deployment. ## Common errors | Symptom | Cause | Fix | | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | Users are unaffected by a node failure sometimes and cut off other times | Clients, DNS or an integration point at a node's own address instead of the virtual address | Point everything at the virtual address; keep node addresses for monitoring and administration only | | A recording plays sometimes and 404s other times | Recordings are on the local **Server** backend, so each file only exists on the node that produced it | Configure external object storage and make it the default backend | | A node is up but its sessions fail | One of that node's connectors is **Offline** while the virtual address keeps sending it traffic | Check the components list per node, and monitor `/api/health/` per node rather than only the virtual address | | An unexpected component appears in the list | Registration was left enabled after the build | Clear **Registration**, and confirm what registered itself and from which address | | One-time passwords fail on one node only | That node's clock has drifted; TOTP is validated to the second | Synchronise the clock on every node, not just the one you built first | ## Related pages * [Install a single node](/pam/deploy-operate/install-single-node) * [System requirements](/pam/deploy-operate/requirements) * [Network and connectivity requirements](/pam/deploy-operate/network-requirements) * [Broker](/pam/administration/connectivity/broker) * [Gateways](/pam/administration/connectivity/gateways) # Certificates and HTTPS Serving the console over HTTPS: the name the certificate has to match, the Site URL setting that has to agree with it, and what breaks quietly when the two disagree. ## What this is and when to use it Two separate things have to line up before the console is properly served over HTTPS, and confusing them is the reason this page exists: * **The certificate** that terminates HTTPS for web access, installed on the server and matching the DNS name your users type. * **Site URL**, a setting that tells the solution its own public address. The certificate makes the browser stop warning. Site URL is what the solution puts into notification email links, SSO redirects and internal callbacks. Getting the certificate right and leaving Site URL alone produces an installation that looks finished — the login page loads over HTTPS with no warning — and quietly breaks single sign-on and every link the system sends by email. Certificates elsewhere in the product are different trust chains and are not configured here: LDAPS uses its own certificate files loaded on the appliance, the broker authenticates gateways and connectors with its own PKI, and SMTP TLS is configured with the mail server. Fixing the console certificate does not touch any of them. {% hint style="warning" %} **Installing the certificate is not a self-service step.** DataDike implementation support imports your wildcard on the server by command line. A Settings screen for uploading a wildcard or subdomain certificate also exists; which of the two paths applies depends on your installation and version, and support will confirm it. {% endhint %} ## What is established | Fact | Note | | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | The web interface is served over HTTPS for browser access | Stated as a platform characteristic | | Either your own certificate or automatic issuance can be used for web access | Which of the two applies to your installation and version has to be confirmed with support; the source states no more than that both exist | | The certificate is imported on the server by implementation support | Stated for the wildcard case | | The address must be a DNS name that resolves for your users | A certificate matches names, and the temporary setup path uses a hosts-file entry that only exists on one machine | ## Before you start * **Settle the DNS name first.** The certificate matches the name users type, Site URL is built from it, and changing it later means revisiting both. * **Have the certificate.** A wildcard or a subdomain certificate covering that name. * **Know your two DNS stages.** The source describes the setup deliberately in two: a **temporary** stage, where you add a hosts-file entry on your own machine purely to reach the appliance during setup, and the **definitive** stage, where records exist in your private DNS — plus your public DNS, if you publish the console to the internet through NAT/DNAT. The hosts entry is scaffolding; leaving it in place is how one administrator ends up seeing a working system nobody else can reach. * **Engage implementation support** for the import. ## Steps 1. **Fix the hostname and create the definitive DNS records** for the name the certificate covers — private DNS, and public DNS as well if the console is published externally. 2. **Have support import the certificate** on the server. 3. **Set Site URL** under **System Settings › General › Basic** to the full URL of that name, with the `https://` scheme and **no trailing slash**. 4. **Restart the dependent components** after changing Site URL. The source is explicit that the change needs this to be applied. 5. **Remove the temporary hosts-file entry** from your own machine, so that you are testing what everyone else sees. ## What Site URL is used for This is why step 3 is not cosmetic. Site URL is consumed internally by: | Consumer | Effect of a wrong value | | ----------------------------------------------------------------------- | --------------------------------------------------------------------- | | Links in notification email — alerts, access approvals, password resets | Recipients get a link to the old address, or to an IP over plain HTTP | | Redirects after SSO authentication (SAML2, OIDC, OAuth2) | Federated login fails or loops, while local login keeps working | | Internally generated callbacks and webhooks | Integrations fail to call back | | Remote access client download, where configured | Clients download from an address that may not resolve for the user | It is required, and it must be reachable from the clients that use the platform — not merely resolvable on the server. ## How to verify it worked Each check below exercises a different consumer of the configuration, because the browser padlock only proves the first one. 1. **Open the console by the exact DNS name over HTTPS**, from a machine with no hosts-file entry. No warning, and the certificate's name matches the name in the address bar. 2. **Fetch the unauthenticated health endpoint over HTTPS on that same name**: `/api/health/` should return its JSON. This confirms TLS terminates on the name and the application answers behind it, which a static error or maintenance page would not. 3. **Trigger something that sends a link** — a notification email you can receive — and confirm the link uses the HTTPS name rather than an IP or `http://`. This is the check for Site URL, and nothing about the browser view substitutes for it. 4. **Perform one login through your identity provider.** The post-authentication redirect has to land on the HTTPS name. A stale Site URL breaks exactly this while leaving local login healthy, so testing with the local admin account proves nothing here. 5. **If a vulnerability scanner or other integration consumes the credential API**, confirm its connector still works: it requires the HTTPS base URL and a certificate its own trust store accepts. An internal CA that browsers trust because of a group policy is not necessarily trusted by a scanner appliance. {% hint style="warning" %} **Nothing in the source documents an expiry alert for the console certificate.** Track the expiry date outside the product — in your certificate inventory or your monitoring system. A certificate that expires takes browser access down for everyone at once, and it does so on a date that was known months in advance. {% endhint %} ## Common errors | Symptom | Cause | Fix | | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | | Console loads over HTTPS, but SSO login loops or lands on the wrong address | Site URL was not updated to the HTTPS name | Set Site URL under **General › Basic**, then restart the dependent components | | Email links point at an IP address or `http://` | Site URL still holds its setup-time value | Same fix. Verify by receiving an email, not by re-reading the field | | Certificate warning in the browser after the install | The name being typed is not covered by the certificate, or DNS still resolves through a leftover hosts entry | Use the name the certificate covers; remove hosts-file entries and confirm the definitive DNS records exist | | Works for the administrator, unreachable for everyone else | The temporary hosts-file entry is still doing the resolution on that one machine | Create the definitive private DNS records, and public records if the console is published | | A scanner or A2A integration cannot connect | Base URL without HTTPS, or a certificate the integration does not trust | Use the HTTPS base URL and make the certificate trusted by that client | | LDAPS still fails after the console certificate is fixed | LDAP TLS uses its own files — `ldap_ca.pem`, `ldap_cert.pem`, `ldap_cert.key` — loaded on the appliance, and needs a service restart | Handle the LDAP certificates separately from the console certificate | | Gateway connections fail after moving to a release that enforces TLS 1.3 | 5.0.1 enforces TLS 1.3 between the Gateway VM and the server, and its release note states a restart is required | See [Upgrade](/pam/deploy-operate/upgrade) | | Broker enrolments break after changing the broker's address | The broker's address is written into its certificates and enrolment tokens and cannot be changed afterwards | Always address the broker by DNS name; changing it otherwise means reinstalling the broker | ## Related pages * [Upgrade](/pam/deploy-operate/upgrade) * [Monitoring and health](/pam/deploy-operate/monitoring) * [Ports](/pam/reference/ports) * [Core concepts](/pam/get-started/core-concepts) # Upgrade What is established about upgrading the solution, the preparation you own before one, the version-specific traps on record, and how to verify an upgrade afterwards. {% hint style="warning" %} **The upgrade procedure must be validated against the two versions involved — the one installed and the one you are moving to.** No single sequence of steps applies to every pair of versions: at least one release requires a restart, and one range of releases dropped a capability that a later release restored. Establish both version numbers first, read the release notes for everything in between, and confirm the procedure with DataDike implementation support before you start. {% endhint %} ## What this is and when to use it This page covers what happens around an upgrade: the preparation that is yours to do, the version-specific facts on record, and the checks that tell you the upgrade landed. It does not give an upgrade command sequence, because there is none to give honestly. {% hint style="danger" %} **The commands, the order of operations and the rollback path come from DataDike implementation support or your reseller**, for your specific installation and version pair. This page describes the upgrade *model* and records version-specific changes. Do not assemble a procedure from fragments — an upgrade run from a guessed sequence is a data-loss event, not a failed change. {% endhint %} ## What is established about upgrades | Fact | Consequence for you | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | In the SaaS model, hosting, infrastructure and operation are DataDike's responsibility, and subscription licensing includes continuous version updates — fixes and new features — at no additional cost for the term, with vendor support 24x7x365 | You do not run the upgrade. Confirm the window and read the release notes | | Components can be updated individually, without stopping the product | Stated as a capability of the architecture, not as a procedure. It does not mean any given upgrade is non-disruptive — the release notes are what tell you whether a restart is involved | | On-premises installations run active/active | A node can be out of service during the change without the service stopping, but only if the change is actually applied node by node | | Operating system fixes and updates are published and signed by DataDike and applied in a controlled way, with platform compatibility preserved at each update and a managed lifecycle that avoids end-of-life components | The OS and the application are updated through the vendor's channel, not from upstream distribution repositories | | The appliance console offers **Reboot** and **Shutdown** | Use these rather than improvising a shutdown of the appliance | ## Before you start Everything below is preparation you own, whichever party executes the upgrade. 1. **Write down the installed version and the target version.** Every fact on this page and in the release notes is conditional on those two numbers. Without both, nothing here can be applied. 2. **Read the release notes for every version between them**, not just the target's. List each item that requires a restart, changes a default, or removes or restores a capability. See [Release notes](/pam/release-notes). 3. **Take a backup and restore it somewhere.** An untested backup is not a rollback plan. See [Back up and restore](/pam/deploy-operate/backup-and-restore). 4. **Confirm license validity for the window.** All functions stay disabled until a license is imported, and an expired license leaves a seven-day grace period in which to import the new one. An upgrade window is a poor time to discover the license lapsed. 5. **Schedule outside the nightly cleanup.** The maintenance and cleanup tasks run in the early hours — the source cites 02:00 for the daily cleanup jobs and recommends keeping system updates and worker restarts out of the 02:00–04:00 window so that automated tasks are not interrupted mid-run. 6. **Agree who executes the change**, and open the request with support stating both version numbers. 7. **Record what a healthy system looks like now**, before the change, so that "was it like that before?" has an answer afterwards: the current `/api/health/` response, the component list with every status, and both task workers Online. See [Monitoring and health](/pam/deploy-operate/monitoring). ## Version-specific facts on record These come from the release notes and are the reason the warning at the top of this page exists. They apply only to the versions named. | Version or range | What it changes | What it means for you | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- | | 5.0.1 | Enforces TLS 1.3 communication between the Gateway VM and the server | The release note states a restart is required | | 5.0 through 5.0.9 | Editing an asset to give it a custom friendly name was removed in error | If you are on this range, the capability is missing — this is a known regression, not a configuration problem | | 5.1.0 (18 August 2026) | Friendly-name editing reintroduced. Environments that already had individual renames do not lose the customisation | The fix for the range above | | 04 May 2026 note | Reliability and stability improvements to the upgrade process of the gateway VM, with reduced downtime between versions. The note's heading says Broker VM while its body says Gateway VM — treat the component as unconfirmed | Broker and gateway VMs follow their own upgrade path, separate from the platform's | {% hint style="warning" %} **A capability missing after an upgrade is not always a misconfiguration.** The 5.0–5.0.9 friendly-name regression is the documented case: the setting was gone from the console, and no amount of permission or policy work would bring it back. Before troubleshooting a missing feature, check whether the release notes record it as removed. {% endhint %} ## Steps The execution belongs to support. The change around it is yours, and it has a shape: 1. Establish the installed and target versions. 2. Read every release note between them and write down the items that require a restart or change behaviour. 3. Back up, and prove the backup by restoring it into a test instance. 4. Capture the pre-change health baseline described under **Before you start**. 5. Open the change with support, stating both versions and the items you found in step 2. 6. Agree a window outside the nightly cleanup hours. 7. Run the upgrade with support. 8. Verify, using the checks below, before declaring the window closed. Do not compress steps 3 and 4. They are the two that make the difference between a rollback and an incident. ## How to verify it worked An upgrade that returns a login page has proved almost nothing. Work outward from the dependencies: 1. **`/api/health/`** returns `status`, `db_status` and `redis_status` all true. On a cluster, poll the virtual address **and each node individually** — a node left on the old version, or left out of the restart, is invisible behind the virtual address. 2. **System Settings › Components** shows every component **Normal** and none **Offline**. Compare against the baseline you captured: a component that is present but was Normal before and is High load now is a finding. 3. **The task engine is running.** From **System Settings › Operations**, open **Monitoring**: both workers — maintenance and automation — Online, and the queues without a backlog of pending **Messages**. Then check on the Operations list that a short-cycle task's **Date last publish** advances after the upgrade. A worker that came back but is not consuming looks identical to a healthy one until you check this. 4. **One real session per protocol you actually use** — terminal, graphical, database — opened end to end, not just launched. Confirm each appears in the audit trail and that its recording plays back. Protocol connectors are separate components; one of them failing to come back is the most common partial-upgrade symptom. 5. **One automation completes.** Let a credential rotation or a connectivity test run, and confirm success in its execution history. This exercises the automation worker and the assets together. 6. **Log in through your identity provider, with MFA.** Local login working proves less than it seems. 7. **Confirm the server date and time.** If the clock is wrong, OTP codes are rejected and MFA login fails — the source names an incorrect server date and time as the cause of the invalid OTP error. A reboot during an upgrade is exactly when a clock drifts. 8. **Open the console by its HTTPS name** and confirm the certificate still serves correctly. See [Certificates and HTTPS](/pam/deploy-operate/certificates). ## Common errors | Symptom | Cause | Fix | | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | A capability that worked before is gone | Known regression in the version you moved to — the documented case is custom asset friendly names, removed between 5.0 and 5.0.9 | Check the release notes for the range before troubleshooting. For that case, 5.1.0 restores it | | MFA or OTP codes rejected immediately after the upgrade | Server date and time incorrect after the restart | Correct the server clock; the source documents this as the cause of the invalid OTP error | | One node in a cluster behaves differently from the others | Not every node was updated or restarted | Poll `/api/health/` on each node as well as on the virtual address, and compare | | Every automatic task stopped after the upgrade | A task worker did not come back | **Operations › Monitoring**, Workers tab; the task service on that server needs restarting | | A setting changed in the appliance configuration file has no effect | Configuration held in the appliance's `config.txt` is read at service start | The services have to be restarted after the file changes | | Gateway connections fail after moving to 5.0.1 | That release enforces TLS 1.3 between the Gateway VM and the server, and states a restart is required | Restart as the release note requires; confirm the gateway side supports TLS 1.3 | | Sessions open but nothing is recorded | The recording or video-processing component is offline, or the storage backend is unreachable | Check **Components**, and the **Storage — Connectivity** notification | ## Related pages * [Release notes](/pam/release-notes) * [Back up and restore](/pam/deploy-operate/backup-and-restore) * [Monitoring and health](/pam/deploy-operate/monitoring) * [Certificates and HTTPS](/pam/deploy-operate/certificates) # Availability and continuity Availability levels, redundancy, continuity objectives and the update model, for the SaaS and on-premises delivery modes. ## What this is and when to use it DataDike PAM is delivered either as **SaaS**, on the DataDike cloud, or **on-premises**, in the customer's own data centre. Both are designed for high availability, so that losing one component does not interrupt privileged access. This page states the published availability terms and continuity objectives for each mode. Use it when the question is what is guaranteed rather than how it is built: a security questionnaire, a risk review, a continuity plan, or simply what happens when a node dies. For how a cluster is actually assembled, see [Install a high-availability cluster](/pam/deploy-operate/install-cluster). For what the architecture does with a failure, see [Architecture and components](/pam/get-started/architecture). {% hint style="warning" %} The figures below are the published terms. The SLA, the support window and the hosting region that apply to a given deployment are the ones stated in its contract. {% endhint %} ## SaaS Delivered as Software-as-a-Service, hosting, infrastructure and operation are DataDike's responsibility, under these terms: | Term | What is published | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Availability SLA | **99.9% minimum**, measured over the contract period | | Licensing | By subscription, including **continuous version updates** — fixes and new features at no extra cost while the subscription runs | | Hosting | **In the country closest to the customer's geolocation where DataDike offers infrastructure services**, with an external replica placed by lowest-latency geolocation | The support window, the severity levels and the response times are published separately, in [SLA and support](/pam/deploy-operate/sla-and-support). ### Redundant local connector The SaaS offer includes a **redundant local connector**, so that access keeps working if the link to the cloud drops, without users or components noticing. * **Automatic, real-time synchronisation between components.** If one site's components become unavailable, the other site's components take over every service with no data loss and no performance degradation. * **One-way connection.** Connections are only ever made from the customer environment towards DataDike's cloud, never the reverse. This matters for a firewall review: no inbound rule from the internet is required. ## On-premises Installed in the customer's data centre, the solution runs **active/active**. Additional items needed to make that work are supplied according to the sizing — database or Windows RDS licensing and HA licences, for example. The list for a given deployment comes from DataDike, not from this page; see the gaps table in [System requirements](/pam/deploy-operate/requirements). ## Continuity and recovery Both modes share the same continuity design: | Objective | Value | | ------------ | ---------------- | | Architecture | Active/active | | **RTO** | Under 30 seconds | | **RPO** | Under 1 second | These figures assume the active/active reference architecture as sized by DataDike for the deployment, including the database and storage replication it specifies. On-premises they hold to the extent that the infrastructure meets that sizing, so confirm the target for your own deployment before committing to these numbers in a continuity plan. * **Backups** carry no retention restriction over the years, and are encrypted and protected against tampering. * **Component redundancy** removes the single point of failure from the vault, the session-brokering proxy and the administration console. {% hint style="danger" %} High availability is not a backup, and the RPO above is not a retention policy. Replication propagates a deletion exactly as fast as it propagates a write. See [Back up and restore](/pam/deploy-operate/backup-and-restore). {% endhint %} ## Separation between customer environments Different customers' environments operate **logically segregated and independent**: consoles, vaults and audit trails with no relationship between them. ## How to verify it worked Availability terms are only worth what a test proves. 1. **Fail a node on purpose**, in a maintenance window, and measure how long access actually takes to return. That measurement is the recovery time of your own deployment. 2. Confirm what the failover cost you: check whether sessions open at the moment of the failure survived, and whether the audit trail recorded them continuously. 3. For SaaS, test the redundant local connector by dropping the link to the cloud, not by reading about it. 4. Restore a backup into a spare environment and time it. An untested backup is an assumption. Record the date and the measured figures. A continuity review is answered by the last test, not by the design objective. ## Related pages * [SLA and support](/pam/deploy-operate/sla-and-support) — the availability figure, the severity levels and the response times * [Install a high-availability cluster](/pam/deploy-operate/install-cluster) — how the active/active arrangement is built * [Back up and restore](/pam/deploy-operate/backup-and-restore) — what high availability does not cover * [System requirements](/pam/deploy-operate/requirements) — sizing, and the licensing that on-premises HA adds * [Monitoring and health](/pam/deploy-operate/monitoring) — watching an instance so you learn about a failure before your users do * [Architecture and components](/pam/get-started/architecture) — what each redundant component does # SLA and support The published service commitments: availability, severity levels, how fast a critical incident gets a first response, who answers, in which language, and through which channel. ## What this is and when to use it This page states the service commitments: how available the service is, how an incident is classified, how quickly it gets a first response, and how to reach the people who answer. Use it when the question is what is guaranteed, rather than how the product is built: a procurement questionnaire, a risk review, an operating runbook, or deciding what to do at two in the morning. {% hint style="warning" %} The figures below are the published terms. The SLA, the support window and the severities that apply to a given deployment are the ones stated in its contract. {% endhint %} For how the architecture keeps the service up, and for recovery objectives, see [Availability and continuity](/pam/deploy-operate/availability-and-sla). ## Availability | Term | What is published | | ---------------- | ---------------------------------------------------- | | Availability SLA | **99.9% minimum**, measured over the contract period | This figure applies to the SaaS delivery mode, where hosting, infrastructure and operation are DataDike's responsibility. On-premises, availability depends on the customer's own infrastructure, and the architecture supplied to support it is described in [Availability and continuity](/pam/deploy-operate/availability-and-sla). ## Severity levels Severity is decided by **impact on the ability to work**, not by how urgent the request feels. The test that separates the levels is whether a workaround exists and how many people are stopped. | Level | Definition | Example | | ------ | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | **P1** | The service is unavailable, or nobody can open a privileged session. No workaround | The console does not answer; every session attempt fails; the vault cannot release credentials | | **P2** | Severe degradation with the service running. A component or a protocol is down, and there is no acceptable workaround | Recordings stop being written; one access protocol fails while others work; rotation fails across many accounts | | **P3** | A functional failure with a workaround available, or affecting a small group | A report will not export; one automation fails while the manual path works | | **P4** | A question, a configuration request, or a suggestion | How to set up an authorization; a request to review a policy | {% hint style="info" %} **The line between P1 and P2 is "no workaround and nobody is working".** Without that objective test every incident is opened as P1, and a severity scale where everything is critical prioritises nothing. {% endhint %} ## Response times | Severity | Coverage | Committed first response | | -------- | ------------------------- | ------------------------- | | **P1** | **24x7x365** | **2 hours** | | **P2** | **24x7x365** | **4 hours** | | P3 | 09:00 to 17:00 local time | Within the service window | | P4 | 09:00 to 17:00 local time | Within the service window | First response means a qualified engineer engaged on the case, not an automatic acknowledgement from the portal. P1 and P2 are answered around the clock, so their hours run on the clock: a P2 raised at 23:00 is due at 03:00, not the next morning. P3 and P4 are handled within the service window below. ## The support team and its window | Term | What is published | | --------- | ------------------------------------------------------------------------------- | | Level | **Level 3 (specialist) only.** There is no first or second line to pass through | | Window | **09:00 to 17:00** local time in each country | | Languages | **English, Spanish and Portuguese** | ### Outside the window Outside 09:00 to 17:00, cover is **24x7x365** for: * **P1 and P2 incidents.** * **Unavailability** of the service. * **Change windows agreed in advance**, scheduled with the customer. P3 and P4 wait for the next business day in that country. ## How to open a ticket Tickets are opened and followed at **`core.datadike.com`**, which is the single channel for support. Opening there is what starts the clock on the response times above. To make a case actionable on the first read, include: * The **severity** you are claiming, and why, against the definitions above. * The **instance** concerned, and whether it is SaaS or on-premises. * **When it started**, and what changed immediately before. * What you have **already tried**. ## A single point of contact Support is delivered by the engineering organisation that builds the product, not by a reseller passing your case along. A case opened at `core.datadike.com` reaches that organisation directly, so there is no second case to open with a vendor behind us, and no handover between companies while an incident is open. Where a partner is involved in the deployment, that does not split the case: the ticket stays in one queue with one owner. ## How to verify it worked Three checks, worth doing before you need them: 1. **Confirm your team can reach the portal.** Everyone who might open a P1 at three in the morning should already have working access to `core.datadike.com`, not be requesting it during the incident. 2. **Agree the severity definitions internally.** Print the table above and put it in your own runbook. The disagreement you do not want is the one about whether something is a P1 while it is happening. 3. **Open a P4 in calm conditions.** It proves the channel works, and it tells you what information the team asks for. ## Common errors | Symptom | Cause | Fix | | ---------------------------------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | A serious case sat overnight | It was opened as P3 or P4, which are business-hours severities | Open incidents that stop people working as P1 or P2, against the definitions above | | The clock seems not to have started | The case was raised by e-mail or through an individual, not at the portal | Open it at `core.datadike.com`, which is the channel the commitments are measured against | | Everything gets opened as P1 | The severity definitions were never agreed internally | Adopt the table above in your runbook, using the workaround test | | Support answers in a language your team does not use | The ticket did not state the preferred language | State it on the case. English, Spanish and Portuguese are available | ## Related pages * [Availability and continuity](/pam/deploy-operate/availability-and-sla) — the architecture behind the availability figure, and the recovery objectives * [Back up and restore](/pam/deploy-operate/backup-and-restore) — what high availability does not cover * [Monitoring and health](/pam/deploy-operate/monitoring) — noticing a failure before your users report it * [Upgrade](/pam/deploy-operate/upgrade) — how a version change is applied # Back up and restore Backing up the installation — database, configuration and recordings — where each of those actually lives, and the test restore that turns a backup into something you can rely on. ## What this is and when to use it This page is about backing up **the installation**: the database, the configuration, and the session recordings. It is what you need to bring the service back after losing a server. It is not the credential backup. That is a separate feature — an encrypted export of the vault, delivered by email, SFTP or webhook, with the decryption key split between two custodians — and it exists for a different scenario: recovering strategic credentials without restoring the environment at all. It is documented under [The credential vault](/pam/administration/accounts/vault). Configure both; they cover different disasters. {% hint style="danger" %} **A backup that has never been restored is a hypothesis.** The backup job reporting success proves that a file was written, not that anything can be recovered from it. Everything under [How to verify it worked](#how-to-verify-it-worked) exists because that distinction is where recoveries fail. {% endhint %} {% hint style="warning" %} **The backup routine for an installation is defined with DataDike implementation support.** The commands, the schedule and the destinations depend on the deployment. What follows is what the platform is specified to do and what the routine has to cover, rather than a sequence to run as it stands. {% endhint %} ## What has to be in the backup Four things, in three different places. A backup covering only the first is the most common way a restore fails. | What | Where it lives | Why it needs separate thought | | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **The database** | Internal to the appliance | Holds users, assets, accounts, authorizations, and the audit and session records. The platform supports backup and recovery of the database and of the software configuration | | **Configuration that is not in the database** | The appliance configuration file, `/opt/datadike/config/config.txt` — the file the syslog settings and the cleanup interval are set in | Changes to it take effect only when the services restart, which also means a restored file does nothing until the services come back | | **Session recordings** | The object storage backend configured under **System Settings › Storage › Object Storage** | By default this is the `default` backend, type Server — the local filesystem of the server. If you moved it to an external bucket, that bucket is backed up on its own terms and a database backup does not touch it | | **The broker PKI**, if you use a broker | The broker VM | The certificates are the trust anchor for every gateway and connector enrolled through that broker | {% hint style="warning" %} **Back up the broker VM, and address the broker by DNS name.** Losing the broker VM without a backup means reinstalling it and re-enrolling every remote gateway and connector. And the address is written into the certificates and the enrolment tokens: if the broker was addressed by DNS name you can point that name at a restored VM and the certificates stay valid, but if it was addressed by a literal IP the address cannot be changed afterwards without reinstalling the broker. {% endhint %} ## What the platform is specified to do These are the capabilities stated for the solution. Treat them as the shape of what to ask for, and confirm how each is configured in your installation. | Capability | As stated | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Destinations | Backup and restore of all data and configuration, exportable to a remote server via rsync or over CIFS/NFS network shares | | Off-site copies | System backups, logs, videos and credentials can be extracted to a server in a remote data centre, so that all configuration and data can be restored from there | | Contents protection | No account or password appears in clear text in the backup file | | Backup retention | Backups without a retention restriction, encrypted and protected against tampering; reports and logs retained in backup for at least ten years, and session recordings for at least ten years | | Live retention | Reports and historical files remain available without a restore for at least 360 days | ## Backup is not the same as high availability The architecture already protects against a node failing: active/active operation, database replication with automatic primary election, cache and queue replication with failover, storage shared between nodes, and a single virtual address in front. The stated continuity objectives are **RTO of one hour or less and RPO of fifteen minutes or less**. None of that is a backup. Replication propagates a deletion exactly as fast as it propagates a write. High availability covers a node dying; the backup covers something being deleted, corrupted, or changed wrongly — including by you, during a change window. ## Before you start * **Decide the destination** — remote server over rsync, or a CIFS/NFS share — and confirm the appliance can reach it. An off-site copy is what survives the event that takes the primary site. * **Find out where recordings actually are.** Open **System Settings › Storage › Object Storage** and note which backend is marked **Default**. Exactly one is. If it is an external bucket, its backup is a separate arrangement. * **Confirm the credential backup separately**, including whether two custodians are configured — with only one, the key is not split at all. See [The credential vault](/pam/administration/accounts/vault). * **Have somewhere to restore into.** A test instance is not optional equipment; it is the only place the verification below can happen. * **Take a full backup before any structural change**, and specifically before enabling and synchronising an external account storage vault — the source calls this out, along with testing that integration in a staging environment first. ## Restoring {% hint style="warning" %} **No restore procedure could be ported: the source does not document one.** Engage DataDike implementation support for the restore of an installation. What follows is what the source does establish about recovery paths, which is worth knowing *before* you need them. {% endhint %} **Credentials can be recovered without restoring the environment.** The credential backup can be opened with its encryption key, so that in a disaster strategic credentials are recoverable even while the platform itself is unavailable. This is the fastest recovery path for the case "we need the passwords right now", and it is entirely separate from restoring the installation. **Recovering the backup encryption key needs several people.** The key recovery process assigns administrators as custodians of parts of the key, and a predefined number of them must be present to reconstruct it during disaster recovery. {% hint style="danger" %} **The vault key must not be held by a single person.** That is a design requirement of the solution, not a preference. It also means recovery is a scheduled, multi-person activity: find out now who the custodians are and whether they are all still with the organisation, rather than during the incident. {% endhint %} **A restored broker keeps its certificates only if it was addressed by DNS name.** Otherwise the broker is reinstalled and every remote gateway and connector is re-enrolled. ## How to verify it worked This is the section that matters. Restoring is the only test of a backup, and the checks below are ordered so that each one covers a gap the previous one cannot see. 1. **Restore into a test instance** — never over production. If you cannot name the date of your last successful test restore, you do not have a verified backup, whatever the job history says. 2. **Check `/api/health/` on the restored instance**: `db_status` and `redis_status` both true. This confirms the restored database is not just present but reachable and answering. 3. **Check System Settings › Components**: every component **Normal**. A restore that brings back the database but not the components produces a console that loads and a platform that cannot open a session. 4. **Open a real session** on the restored instance, on a protocol you use, and confirm it completes and is recorded. 5. **Play back a recording made before the backup was taken.** This is the check that catches the most common gap in the whole procedure: the recordings live in a storage backend, and a database-only backup restores every session *record* while every replay is missing. If playback fails here, your backup does not cover recordings. 6. **Confirm the server date and time on the restored instance.** A wrong clock makes OTP codes invalid, so MFA logins fail on an otherwise perfectly restored system — see [Multi-factor authentication](/pam/administration/identities/mfa). 7. **Verify the credential backup on its own terms**: the job succeeded, and each custodian received their part — two parts, if you configured two custodians. 8. **Write down the date, the version restored, and what failed.** The value of a test restore is mostly in the list of things that did not work. ## Common errors | Symptom | Cause | Fix | | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | Restored instance works, but no session replay will play | The recordings live in the object storage backend, which the database backup never touched | Back up the storage backend too; check which backend is **Default** under **Storage › Object Storage** | | Recording files are gone while the session records still list them | Console retention governs database records; the files' lifecycle is the bucket's own lifecycle policy, configured separately | Align the bucket lifecycle policy with your retention requirement | | An old audit event cannot be found at all | Its retention window elapsed and the nightly cleanup deleted the record. No error is shown — an empty result looks like "it never happened" | Set retention values against your audit obligations before you need the evidence | | Credential backup arrives as one file that a single recipient can open | Only one custodian was configured, so the key was never split | Configure both custodians — see [The credential vault](/pam/administration/accounts/vault) | | Backup encryption key cannot be reconstructed | Fewer custodians available than the number required to recover the key | The threshold is a design requirement; keep the custodian list current and documented | | Broker restored, but gateways and connectors never reconnect | The broker was addressed by a literal IP, so its certificates cannot be re-pointed at a restored VM | Address the broker by DNS name. Otherwise reinstall the broker and re-enrol each remote point | | A restored configuration file appears to have no effect | Configuration in the appliance's `config.txt` is read when the services start | Restart the services after restoring the file | | MFA login fails on a freshly restored instance | Server date and time incorrect, so OTP codes are rejected | Correct the server clock | ## Related pages * [The credential vault](/pam/administration/accounts/vault) * [Session recordings](/pam/administration/audit/recordings) * [Audit trail](/pam/administration/audit/audit-trail) * [Upgrade](/pam/deploy-operate/upgrade) * [Monitoring and health](/pam/deploy-operate/monitoring) # Monitoring and health How to tell whether the installation is healthy: the health endpoint an external monitor should poll, the console screens that show component and task state, and the alerts worth subscribing to. ## What this is and when to use it This page is about the health of the installation — is the database reachable, are the components up, are the background tasks running. It is not about watching what a user is doing inside a session; that is live session monitoring, under **Audit › Sessions › Online**, and it answers a different question. Health monitoring has three layers, and most installations only set up the second one: 1. **An external monitor** polling the health endpoint. This is the layer that wakes someone up at 03:00. 2. **Console screens** — **System Settings › Components** and the task dashboard reached from **System Settings › Operations**. These are accurate but you have to be looking at them. 3. **In-product alerting** — notification subscriptions for storage connectivity and component performance. ## The health endpoint The solution exposes an unauthenticated health endpoint at `/api/health/`. It returns JSON: ``` {"status":true,"db_status":true,"db_time":0.0083,"redis_status":true,"redis_time":0.0022,"time":1788772352} ``` | Field | Meaning | | -------------- | ------------------------------------- | | `status` | Overall result | | `db_status` | Whether the database is reachable | | `db_time` | Database response latency, in seconds | | `redis_status` | Whether Redis is reachable | | `redis_time` | Redis response latency, in seconds | | `time` | Server timestamp | {% hint style="info" %} **Point your external monitor at this endpoint, not at the front page.** A monitor that fetches the login page proves only that the web server answered. This endpoint proves the database and Redis are reachable — the two dependencies whose loss makes the console useless while still returning a page. {% endhint %} The two timing fields are latency in seconds. Alerting only on `db_status: false` catches the outage; trending `db_time` and `redis_time` catches it coming. **On a cluster**, the installation is fronted by a single virtual address, and each node also answers `/api/health/` directly. Poll both: the virtual address tells you whether the service is up, and the per-node responses tell you whether one node has quietly dropped out while the address still answers from the others. A monitor that watches only the virtual address cannot tell "the cluster is down" from "one node is down", and the second condition is the one that stays unnoticed for weeks. ## Component health in the console **System Settings › Components › Components** lists every registered microservice with its live state. | Column | What it tells you | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | **Name** | Registered component, as `[Type]-ServerName` | | **Online sessions** | Sessions the component is handling right now. Zero means idle; a persistently high number suggests it needs another instance | | **Stat** | CPU and memory use of the component process. Near 100% means the resource is saturated | | **Load status** | **Normal**, **Offline**, or **High load** | | **Remote address** | Address of the server where the component runs | **Offline is the state that matters.** If the core API component is offline the whole platform is inaccessible. If a protocol connector is offline, sessions of that protocol stop while everything else looks fine — the console still loads, so the failure reads as "RDP is broken" rather than "a component is down". The source recommends configuring external alerting for offline components through a monitoring system — Zabbix, Prometheus and Datadog are the examples given — rather than relying on someone opening this screen. ## The task engine: workers and queues All automatic work runs in background tasks: log cleanup, periodic asset checks, account synchronisation, and the Ansible-based automations. The **Monitoring** button at the top of **System Settings › Operations** opens the task dashboard in a new browser tab. **Workers tab.** Each row is a worker process named `queue@hostname`. Two workers are expected: the default maintenance worker, and the automation (Ansible) worker. Columns are **Worker**, **Status** (Online / Offline), **Active**, **Processed**, **Failed**, **Succeeded**, **Retried**, and **Load Average** (system load over 1, 5 and 15 minutes). **Tasks tab.** Individual executions: **Name** (the internal task path, in the form `module.submodule.task_name`), **UUID** (click through for the full detail), **State** (`SUCCESS`, `FAILURE`, `PENDING`, `RETRY`), **args** and **kwargs**, **Result**, **Received**, and **Started**. **Broker tab.** Queue state. Redis is the task broker, with two queues configured: `default` for maintenance and system checks, and `ansible` for the automations that talk to managed assets. Columns are **Queue**, **Messages** (pending), **Unacked** (delivered to a worker but not yet confirmed), **Ready**, **Consumers**, and **Idle since**. {% hint style="warning" %} **An offline worker stops every automatic task, silently.** Cleanup, credential rotation, connectivity checks, account synchronisation — all of it. Nothing in the console breaks, so the symptom shows up later as stale data or a rotation that never happened. If a worker is offline, the task service on that server is not running and infrastructure has to restart it. {% endhint %} Two numbers are worth watching over time: * **Failed**, on the Workers tab, together with `FAILURE` states on the Tasks tab. Repeated failures point at asset connectivity, a configuration error, or database inconsistency. * **Messages**, on the Broker tab. A queue that keeps growing means the workers are not consuming as fast as work arrives — server overload, or a stuck worker. The `ansible` queue is the one that backs up in environments with many managed assets, at automation peaks. On the **Operations** list itself, two columns do the same job for scheduled work: a **Success/Total** count shown in red flags failing executions, and **Date last publish** should fall inside the task's own cycle. The source gives the concrete test: a task on a 3600-second cycle that has not run in the last two hours means you should go look at the workers. ## Alerts to subscribe to **System Settings › Notifications › Subscription** binds event types to recipients. Two of the categories are about the infrastructure rather than about user behaviour: | Message type | Fires when | | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | **Storage — Connectivity** | The configured storage backend cannot be reached. This is early warning: it arrives before recordings start failing to save | | **Component — Server performance** | A component shows high CPU or memory use, or degraded performance | | **Sessions — Command reject** | A command in a live session was blocked by the command policy | | **Job — Command reject** | A scheduled job tried to run a blocked command | Each type has its own recipient list, set through **Edit recipient**. A subscription with no recipient is silent, which is indistinguishable from nothing having happened. ## Storage and retention: the growth to watch Retention settings, under **System Settings › Retentions**, set how many days each class of record is kept. The nightly cleanup tasks then delete anything older. {% hint style="danger" %} **Retention deletes evidence, and nothing tells you it happened.** An investigation into an event older than the retention window returns an empty result, not an error — indistinguishable from "it never happened". Decide the retention values against your audit obligations before you need the evidence, not during the investigation. {% endhint %} The second trap is the split between metadata and files: * The retention values in the console control **records in the database**. * The lifecycle of the actual **recording files** is whatever the object storage bucket or container's own lifecycle policy says. They are configured in two different places and do not coordinate. A bucket lifecycle shorter than your session-log retention leaves session records that list a replay which no longer exists; a longer one keeps files after the records that pointed to them are gone. Recording storage backends are managed under **System Settings › Storage › Object Storage**, where exactly one backend is marked **Default**; check which one that is before you reason about where anything is kept. Graphical (RDP) sessions consume far more space than terminal sessions, so storage growth tracks the mix of protocols you use, not the number of sessions. ## Network diagnostics from the server **System Settings › Utils** runs Ping, Telnet, Nmap, Tcpdump and Traceroute **from the server**, with the result streamed into the Output area. That is the point of it: the result reflects connectivity between the solution and the asset, not between your workstation and the asset — which is the question you actually have when a session will not open. * **Telnet** is the useful one for a failing asset: it tests a TCP port, where Ping only tests ICMP. Use it before registering a new asset to confirm the protocol port is reachable from the server. * **Ping** shows resolved address, latency and packet loss, so it doubles as a DNS resolution check from the server. * **Tcpdump** and **Nmap** are the heavy tools. Always apply source and destination filters to a Tcpdump in production, and treat the captured output as sensitive — it can contain the traffic of managed assets. {% hint style="warning" %} **Utils are reconnaissance tools running from inside your network.** The **Tools in the cockpit** switch on the **Basic** tab disables them entirely, for everyone, regardless of role permissions. Where they are enabled, restrict them by role to network and infrastructure profiles. {% endhint %} ## How to verify your monitoring actually works Monitoring is the one thing that fails without a symptom, because a monitor that never fires looks exactly like a system that never breaks. Check the monitor, not the system: 1. **Confirm your external check tests the endpoint's content, not just its status code.** Verify the monitor alerts when `db_status` or `redis_status` is `false` — an endpoint returning HTTP 200 with `db_status: false` is a real outage, and a monitor watching only the response code reports it as healthy. 2. **On a cluster, compare the virtual address response with each node's.** If your monitor only has one target, it cannot see a single node dropping out. 3. **Confirm an alert reaches a person.** Open each subscription you rely on and check that **Receiver** is not empty. 4. **Confirm the task engine is alive rather than merely present.** On the Workers tab both workers should be Online, and on the Operations list the **Date last publish** of a short-cycle task should be recent. A worker can be listed and idle. 5. **Confirm the storage path end to end** by opening a recent recording and playing it back. Storage connectivity alerts tell you the backend is unreachable; only a playback tells you writes are landing where reads look. ## Common errors | Symptom | Cause | Fix | | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | | Monitor reports healthy during a database outage | The check tests the login page or the HTTP status code only | Poll `/api/health/` and alert on `db_status` and `redis_status` | | The console loads but one protocol cannot open sessions | That protocol's connector is Offline | Check **System Settings › Components**; restart the component's service on the server it runs on | | Whole platform inaccessible | The core API component is offline | Same screen; the core API is the single component whose loss takes everything with it | | Rotations, cleanups and connectivity checks all silently stopped | A task worker is Offline, so no scheduled task runs | Check the Workers tab from **Operations › Monitoring**; restart the task service | | Queue **Messages** keeps climbing | Workers are not consuming at the rate work arrives, or one is stuck | Check worker status and load; the `ansible` queue backs up first in large environments | | Session records exist but replays will not play | Recording files were removed by the bucket's own lifecycle policy, which is independent of console retention | Align the bucket lifecycle with your retention requirement | | An old event cannot be found in the audit trail at all | Its retention window elapsed and the nightly cleanup deleted the record; no error is raised | Set retention values against your audit obligations in advance | | Alerts configured but never received | The message type has no recipient | Set **Receiver** per message type under **Notifications › Subscription** | | A diagnostic tool is missing from the console for an administrator | **Tools in the cockpit** is disabled, which overrides role permissions | Re-enable it on the **Utils › Basic** tab, then restrict by role | ## Related pages * [Audit trail](/pam/administration/audit/audit-trail) * [Session recordings](/pam/administration/audit/recordings) * [Reports](/pam/administration/audit/reports) * [Ports](/pam/reference/ports) * [Back up and restore](/pam/deploy-operate/backup-and-restore) # Reference | Page | What it covers | | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [API](/pam/reference/api) | Where the interactive API documentation lives, how a client authenticates, and which endpoint families this wiki documents in full. | | [Configuration fields](/pam/reference/configuration-fields) | A field-by-field lookup for the System settings area — what each setting does and the value it ships with, organised by the screen it appears on. | | [Ports and protocols](/pam/reference/ports) | The default port each platform uses to reach an asset, and why the effective port is set per asset rather than globally. | | [Supported platforms](/pam/reference/supported-platforms) | A quick answer to "is my technology supported?" — the built-in platforms by category, with the non-obvious choices flagged and a pointer to the Platforms page for the detail. | | [Compliance mappings](/pam/reference/compliance-mappings) | Every control each compliance package answers, and which operational report the package embeds as the evidence for it. | | [Glossary](/pam/reference/glossary) | Every term this documentation uses, defined as DataDike PAM uses it, with a link to the page that documents each one. | # API Where the API specification lives, the three ways a client authenticates, the conventions every endpoint shares, and what each endpoint family covers. ## What this is and when to use it The solution exposes a REST API over HTTPS. The console is itself a client of it: every screen you use is calling the same endpoints an external system would, which is why anything the console can do is reachable programmatically. Use it to register assets from a CMDB, retrieve a credential inside a pipeline, export audit records into a data warehouse, or drive onboarding and offboarding from an identity system. ## Where the specification lives Two addresses on your own instance, both generated from the version actually running: | Address | What it is | Use it for | | ------------------------------------------ | ------------------------- | ------------------------------------ | | `https:///api/docs` | Interactive documentation | Browsing endpoints and trying a call | | `https:///api/swagger.json` | OpenAPI 2.0 specification | Generating a client in any language | {% hint style="info" %} Read the specification from **your own instance** rather than any list written down elsewhere. It matches the build you are integrating with, which a wiki page cannot promise. {% endhint %} Every endpoint sits under the `/api/v1/` prefix, and the API answers over HTTPS only. A client that cannot validate the instance's certificate fails at the transport layer before authentication matters, so a self-signed certificate has to be trusted by the calling machine first. ## How a client authenticates There is no anonymous access. Three mechanisms are available, and they carry different identities. | Mechanism | Identity | How the credential is obtained | | ------------------------------------- | -------------- | --------------------------------------------------------------- | | **Access key signature** | A console user | **Profile › Access keys**, which issues an ID and a secret | | **Integration application signature** | An application | Registered by an administrator, which issues an ID and a secret | | **Bearer token** | A console user | `POST /api/v1/authentication/auth/` with username and password | ### Signing a request Both signature mechanisms use HTTP Signature with HMAC-SHA256. The client builds a signing string from the request target and the date, signs it with its secret, and sends the result in the `Authorization` header. ``` (request-target): get /api/v1/assets/hosts/?limit=10 date: Wed, 23 Sep 2026 20:44:35 GMT ``` ``` Authorization: Signature keyId="",algorithm="hmac-sha256", headers="(request-target) date",signature="" Date: Wed, 23 Sep 2026 20:44:35 GMT ``` Three details decide whether the call succeeds: * **The query string is part of the signing string.** Sign the request target exactly as it will be sent, parameters included and in the same order. * **The date must be RFC 7231, in English, in GMT.** A client running on a machine with a non-English locale that formats the date in its own language produces a header the server rejects. This is the most common integration failure, and it only appears outside English-speaking environments. * **An integration application adds `X-Source: jms-pam`.** That header is what distinguishes an application from a user's access key, and without it the request is interpreted as the latter. ### Bearer token A token obtained from the login endpoint is sent as `Authorization: Bearer `. It carries the permissions of the user it was issued to and is short-lived, which makes it suitable for an interactive script and unsuitable for an unattended job. For anything that runs without a person present, prefer a signature. {% hint style="warning" %} An access key carries the full permissions of the user who owns it, so it is as powerful as that person's role. An integration application, by contrast, is scoped twice over: to the accounts it may read and to the source addresses it may call from. **For machine access, prefer an integration application.** {% endhint %} ### Ready-made clients The product ships a working client and its documentation for six languages, served by the instance itself under the integration application's **SDKs** tab. Each one implements the signing described above. | Language | Dependencies | | ---------- | --------------------------- | | Python | `requests`, `httpsig` | | Java | None. Standard library only | | Go | None. Standard library only | | Node.js | `axios` | | PowerShell | None. Built-in cmdlets only | | curl | None | ## Conventions every endpoint shares ### Pagination Collections are paginated with `limit` and `offset`, and answer with a consistent envelope: ```json { "count": 412, "next": "...", "previous": null, "results": [] } ``` ### Searching, ordering and filtering | Parameter | What it does | | ------------ | ------------------------------------------------------------------ | | `search` | Free-text search across the resource's searchable fields | | `order` | Field to sort by. Prefix with `-` to reverse | | *field name* | Exact-match filter. Which fields are filterable varies by resource | ### Discovering a resource's fields An `OPTIONS` request to a collection returns the resource's field metadata: names, types, whether each is required, and the available choices. It is the fastest way to learn a payload without reading the whole specification, and it reflects your own permissions. ### Export formats Collections render as JSON, CSV or XLSX. Add `format=csv` or `format=xlsx` to a `GET`, and the response carries a header row with the same column names the console exports. ### Language Responses honour the `Accept-Language` header and report what they used in `Content-Language`. Error messages, field labels and validation text come back translated. | Sent | Returned | | ------- | ------------------------------------------------------ | | `en` | `Authentication credentials were not provided.` | | `pt-br` | `As credenciais de autenticação não foram fornecidas.` | | `es` | `Las credenciales de autenticación no se proveyeron.` | | `fr` | `Informations d'authentification non fournies.` | For a call authenticated as a console user, that user's own language preference takes precedence over the header. ### Organisations An instance can hold several organisations, and most resources belong to one. Requests carry the organisation in the `X-JMS-ORG` header. A client that omits it operates in the default organisation, which is a common cause of a call succeeding and returning nothing. ## Endpoint families Every family below is covered by the specification on your instance. The operation counts are a measure of surface, not of importance. | Family | Prefix | Operations | What it covers | | ----------------------- | ------------------ | ---------- | ---------------------------------------------------------------------------------- | | Sessions and connectors | `/terminal/` | 249 | Live sessions, recordings, connection endpoints, applets, publishing hosts | | Assets | `/assets/` | 229 | Hosts, databases, devices, cloud, platforms, nodes, zones, discovery | | Accounts | `/accounts/` | 159 | Managed accounts, templates, rotation, discovery, backup, integration applications | | Authentication | `/authentication/` | 100 | Login, MFA, access keys, SSH keys, passkeys, connection tokens | | Tickets | `/tickets/` | 96 | Access requests, approval flows, approvers | | Authorizations | `/perms/` | 77 | Who may reach which asset with which account | | Roles and permissions | `/rbac/` | 75 | Roles, role bindings, the permission catalogue | | Users | `/users/` | 70 | Users, groups, directory synchronisation | | Automation | `/ops/` | 64 | Jobs, ad-hoc commands, playbooks, execution history | | Access control | `/acls/` | 58 | Command filters, login rules, connection method rules | | Gateways | `/brokers/` | 37 | Reverse gateways and the targets reachable through them | | Labels | `/labels/` | 34 | Labels and what carries them | | Audit | `/audits/` | 28 | Login records, operation logs, credential retrievals, file transfers | | Notifications | `/notifications/` | 26 | Channels, subscriptions, message templates | | Settings | `/settings/` | 25 | System configuration | | Behaviour analysis | `/ueba/` | 20 | Behavioural findings and their rules | | Reports | `/reports/` | 19 | Report definitions, runs, downloads | | Vault | `/vault/` | 16 | Credentials kept and shared by hand, in folders | | Organisations | `/orgs/` | 12 | Tenants and their membership | An `/xpack/` prefix carries the features of the licensed edition, and its presence depends on the licence installed. ## Errors Failures answer with a JSON body carrying a human-readable `detail` and a stable `code`: ```json { "detail": "Authentication credentials were not provided.", "code": "not_authenticated" } ``` | Status | Usual cause | | ------ | --------------------------------------------------------------------------- | | 400 | A payload that failed validation. The body names the offending fields | | 401 | No credential, an expired token, or a signature the server could not verify | | 403 | A valid identity without permission for this resource | | 404 | The resource does not exist, or belongs to another organisation | Match on `code` rather than on `detail`, because `detail` is translated and `code` is not. ## How to verify you can reach the API Three checks, in the order that finds problems fastest: 1. **Call the health endpoint.** It needs no credential, which makes it the quickest proof that the network, the hostname and TLS are all working: ```bash curl -s "https:///api/health/" ``` A healthy instance replies with `"status": true`, alongside the state of the database and of the cache. 2. **Call a collection with your credential** and confirm the envelope comes back. `GET /api/v1/users/users/?limit=1` is a safe choice, and a 401 here with a healthy instance points at the credential, not the connection. 3. **Repeat the call from the machine that will run the integration.** An application's allowed source addresses are enforced, so a call that works from your workstation can still be refused from the server that needs it. ## Common errors | Symptom | Cause | Fix | | ------------------------------------------------------------ | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | 401 with a signature that looks correct | The date header was formatted in the machine's own language, or the clock has drifted | Format the date in English, in GMT, and keep the host's clock synchronised | | 401 only when the query string is present | The signature covered the path without its parameters | Sign the request target exactly as sent | | An integration application authenticates as nobody | `X-Source: jms-pam` is missing | Add the header | | A call succeeds but returns an empty collection | The client is operating in the default organisation | Send `X-JMS-ORG` with the intended organisation | | A call works from your workstation and fails from the server | The application's allowed source addresses do not include that server | Add the address to the application | | 403 with a working credential | The user or application lacks permission for that resource | Check the role, or the application's account scope | | `/api/docs` cannot be reached | The instance is addressed by a name the client cannot resolve, or TLS is failing | Use the same address as **System settings › General › Site URL** | ## Related pages * [Application-to-application access](/pam/administration/integrations/application-to-application) — retrieving a credential without a person * [The credential vault](/pam/administration/accounts/vault) — what those endpoints read from * [Audit trail](/pam/administration/audit/audit-trail) — where API calls are recorded * [Configuration fields](/pam/reference/configuration-fields) — the Site URL that clients should address # Configuration fields A field-by-field lookup for the System settings area — what each setting does and the value it ships with, organised by the screen it appears on. Everything below lives under **System settings**, one section per screen. Use it when you are looking at a field and want to know what it does, or when you need to know what a value was before somebody changed it. {% hint style="info" %} This page covers settings configured **in the console**. Parameters set at install time in the server's configuration file are not here; where a console setting depends on one, the dependency is called out. {% endhint %} The defaults given are the values the solution ships with. Several of them are deliberately permissive — `999`, `9999` and `Auto` all mean "effectively no limit" — so read the default before assuming a control is already in force. ## General **System settings › General** | Section | Field | What it does | Default | | ---------- | ---------------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------- | | Basic | Site URL | The publicly reachable address of this instance. Required | | | Basic | Default language | Interface language for new users | | | Basic | Timezone | Timezone applied to timestamps and logs | | | Basic | Logo (with text) | Shown on the login page and at the top left of the console | | | Basic | Logo (without text) | The small mark used where there is no room for the full logo | | | Basic | Site icon | Browser tab icon, `.ico` or `.png` | | | Basic | Login background image | Background of the login page | | | Basic | Login page title | Text on the login page | | | Basic | Interface theme | Console colour scheme | | | Basic | Custom navigation links | Extra links in the top navigation bar, as a JSON array | | | Basic | ICP registration information | Regulatory registration text, for deployments in China | | | Navigation | Document URL | Target of the documentation (**?**) icon in the top bar. Point it at an internal portal if you keep one | `https://wiki.datadike.com` | | Navigation | Support URL | Target of the support option in the top bar — a ticket system, an ITSM tool, or a team channel | `https://wiki.datadike.com` | {% hint style="warning" %} **Site URL** is not cosmetic. It is the address written into notification e-mails, used for the redirect back from SAML2, OIDC and OAuth2 sign-in, used to build internal callbacks and webhooks, and used for remote-access client downloads. Use HTTPS, leave off the trailing slash, and restart the dependent components after changing it — a wrong value produces approval e-mails whose links go nowhere and SSO logins that fail on the way back. {% endhint %} ## Announcement **System settings › Announcement** A banner shown to every user at sign-in — typically the monitoring notice that tells people their session is recorded. | Field | What it does | Default | | ------------ | -------------------------------------------------------------------------------------------------------------------- | ------- | | Announcement | Master switch. With it off, nothing is shown regardless of the other fields | | | Subject | Headline of the notice. Required | | | Content | Body of the notice, rich text, with a preview tab. Required | | | Date start | Date and time the notice starts being shown, `YYYY-MM-DD HH:MM:SS` | | | Date end | Date and time it stops. It hides itself, with no manual step | | | More link | Optional URL behind a "read more" link in the footer of the notice — the acceptable-use policy or the privacy notice | | ## Features **System settings › Features**. Five independent modules, one tab each. | Tab | Field | What it does | Default | | --------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- | | Access requests | Ticket | Lets a user without a direct authorization request temporary access by ticket. The approval flow itself is configured in the authorization rules | Enabled | | Access requests | Approval without login | Approvers act on a link sent by e-mail, without signing in to the console. Intended for executives and external approvers | Disabled | | Access requests | Period | How long an authorization granted by ticket stays valid. Used together with Unit | 7 | | Access requests | Unit | Unit for Period: `day` or `hour`. Use `hour` for on-call access | day | | Job center | Adhoc | Allows immediate, unscheduled command execution across many assets | Enabled | | Job center | Command blocklist | Commands refused in adhoc execution regardless of the user's permissions | `reboot`, `shutdown`, `poweroff`, `halt`, `dd`, `half`, `top` | | Account storage | Vault | Stores account secrets in an external vault — HashiCorp Vault, Azure Key Vault, or AWS Secrets Manager — instead of the local database | Disabled | | Account storage | Record limit | How many historical account records to keep. Below 999, a nightly task deletes the excess; at 999 or above nothing is deleted automatically | 999 | | Chat AI | Chat AI | Enables the in-console AI assistant. The other fields on the tab must be filled for it to work | Disabled | | Chat AI | GPT model | Which model to call. The choice drives both cost and answer quality | | | Chat AI | GPT base URL | Base URL of the OpenAI-compatible service. Point it at a self-hosted service for air-gapped or data-residency requirements | `https://api.openai.com/v1` | | Chat AI | API key | Authentication key for that service. Treat it as a credential and give it a spending limit | | | Chat AI | Agent | System prompt that sets the assistant's scope, behaviour, and answer language. Empty means the model's own default | | | VirtualApp | Virtual app | Global switch for published remote applications. With it off, the whole **Virtual access applications** area disappears from the console | Enabled | {% hint style="danger" %} **Account storage must be prepared on the server before it is switched on here.** `VAULT_ENABLED` and `VAULT_BACKEND` have to be set in the server configuration file first. The synchronisation that follows is **one-way** — local database to remote vault — and once it completes the local database no longer holds passwords at all. Take a full backup before running it; reversing it means another migration. Any later change to the vault configuration needs a service restart to take effect. {% endhint %} {% hint style="info" %} `top` is on the command blocklist for an unobvious reason: it is not destructive, but an interactive monitor never exits, so the job that launched it never finishes. The other defaults are there for the obvious reason. {% endhint %} ## Security **System settings › Security**. Four tabs. | Tab | Field | What it does | Default | | ----------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | | Authentication | Login captcha | Requires a challenge on the login page, against automated brute force | Enabled | | Authentication | Login dynamic code | Requires an additional one-time code at login, sent by e-mail or SMS | | | Authentication | Auto disable threshold (day) | Days of inactivity after which a user account is disabled automatically. Required | 999 | | Authentication | Suspicious login verification | Compares the login address against the user's usual city and requires extra verification, sending a remote-login notice | Enabled | | Authentication | Global MFA | MFA policy for everyone: `Not enabled`, `All users`, or `Only admin users` | Not enabled | | Authentication | Third-party login MFA | Applies MFA to users arriving through LDAP, OIDC, SAML2 and the other external providers as well | Enabled | | Authentication | MFA verify TTL | Seconds a verified second factor stays valid before it is asked for again. Required | 3600 | | Authentication | OTP issuer name | The name authenticator apps display for this instance | | | Authentication | OTP valid window | How many time periods either side of the current one are accepted, to absorb clock drift. Required | 2 | | Login restriction | Login failures count | Failed sign-ins per user before a temporary lock. Required | 7 | | Login restriction | Login failure period (minute) | Window over which those failures are counted. Required | 30 | | Login restriction | Login failures count (IP) | Failed sign-ins from one address before the address is locked out. Required | 7 | | Login restriction | Login failure period (minute), IP | Window over which failures per address are counted. Required | 180 | | Login restriction | Login IP allow list | Addresses, ranges and CIDRs permitted to sign in. When set, nothing outside it can. Accepts `192.168.10.1`, `192.168.1.0/24`, `10.1.1.1-10.1.1.20`, and IPv6 | | | Login restriction | Login IP deny list | Addresses explicitly refused. Same notation | | | Login restriction | Blocked IP's | Read-out of the addresses currently locked out, with the option to release them | | | Login restriction | Only single device login | A new sign-in disconnects the user's other sessions | Disabled | | Login restriction | Only exist user login | Refuses users who do not already have a record here. With it off, a user arriving through an external provider is created on first login | Disabled | | Login restriction | Only from source login | Authenticates the user only against the source recorded on their account. With it off, every enabled method is tried in order and any success signs them in | Disabled | | Passwords | User password expiration (day) | Days before a local password must be changed. A reminder goes out daily for the last five days. Required | 9999 | | Passwords | Recent password count | How many previous passwords are remembered and refused. Required | 5 | | Passwords | Minimum length (User) | Minimum local password length for ordinary users. Required | 6 | | Passwords | Minimum length (Admin) | Minimum local password length for administrators. Required | 6 | | Passwords | Uppercase / Lowercase / Digits / Special characters | Character classes a local password must contain, one checkbox each | | | Sessions | Watermark | Overlays identifying text on web sessions and on recordings. Required | Enabled | | Sessions | Watermark session content | The text of the overlay, built from variables. Default `${name}(${userName})${assetName}${assetAddress}` | | | Sessions | Session share | Allows an active session to be shared with another user, for support or supervision. Required | | | Sessions | Session expire at browser closed | Ends the console session when the browser closes, whatever the idle timeout says | | | Sessions | Allow users to view asset session info | Shows the number of active sessions on an asset in the account-selection dialog. RDP only | | | Sessions | Max idle time (minute) | Idle time after which a connection is dropped. Required | 30 | | Sessions | Max online time (hour) | Total duration after which a connection is dropped regardless of activity. Required | 24 | The variables accepted by **Watermark session content**: | Variable | Resolves to | | ----------------- | --------------------- | | `${userId}` | User ID | | `${name}` | User's full name | | `${userName}` | User's login name | | `${assetId}` | Asset ID | | `${assetName}` | Asset name | | `${assetAddress}` | Asset address | | `${currentTime}` | Current date and time | {% hint style="warning" %} Two things about this tab bite in practice. Once **Global MFA** is set to *All users*, an individual user can no longer turn their own MFA off — which is the point, but it also means a user who loses their authenticator needs an administrator to reset it. And the watermark is reliable on SSH and Telnet sessions, while on RDP it is applied by the graphical connector and **does not always appear when the user connects with a native RDP client**. Do not treat the RDP watermark as a control you can prove. {% endhint %} {% hint style="info" %} The deny list wins. An address that appears in both **Login IP allow list** and **Login IP deny list** is refused. {% endhint %} Turning **Session share** off is the restrictive setting: only the user who opened a session can then reach it. ## Authentication **System settings › Authentication**. One page per identity source, all of which can be enabled at the same time: Local, LDAP and LDAP HA, CAS, Passkey (FIDO2/WebAuthn), OIDC, SAML2, OAuth2, Slack, and Radius. Three fields recur on every provider: | Field | What it does | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | Enable | Only enabled providers appear on the login page | | User attribute | JSON mapping from the provider's attributes to the user record here — which attribute is the username, the name, the e-mail, the groups | | Organization | Which tenant users authenticated by this provider are created in | Each provider publishes three URLs under this instance's own hostname, for registration at the identity provider: `/core/auth//login/`, `/core/auth//callback/`, and `/core/auth//logout/`. For the configuration itself see [Single sign-on](/pam/administration/identities/sso), [LDAP and Active Directory](/pam/administration/identities/ldap-and-ad), and [Multi-factor authentication](/pam/administration/identities/mfa). {% hint style="danger" %} When user authentication comes from AD or LDAP, turn **Public key** off under **Components › SSH & Terminal Protocol**. A user removed from the directory who still has a public key registered here keeps reaching assets with it, straight past your offboarding process. {% endhint %} ## Notifications **System settings › Notifications**. Three tabs: Email, SMS, and Subscription. | Tab | Field | What it does | Default | | ------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | Email | Protocol | `SMTP` or `EXCHANGE` | SMTP | | Email | IP address or hostname | The mail server. The firewall must allow this instance to reach it. Required | | | Email | Port | `25` unencrypted, `465` with implicit SSL, `587` with STARTTLS. Required | | | Email | Account | Username for SMTP authentication. Leave empty for an authorised open relay | | | Email | Password | Password for that account | | | Email | Sender | The From address on everything the solution sends. Use a dedicated mailbox | | | Email | Use SSL | Encrypts from the start of the connection, normally with port 465 | | | Email | Use TLS | Upgrades the connection with STARTTLS after the handshake, normally with port 587 | | | Email | Template | Customises the subject prefix and body of notification mail | | | Email | Recipients | Addresses used by **Test connection**, comma-separated. Testing does not save | | | SMS | Message | Global switch for the SMS channel. With it off, SMS is not used even with a provider configured | | | SMS | Provider | Which gateway to use. **Custom** integrates any provider through a REST API | | | SMS | Code length | Digits in the one-time code sent by SMS | 4 | | SMS | Provider (JSON) | Endpoint and authentication parameters for a custom provider. The structure depends on the provider | | | Subscription | Message type | The event that can raise a notification. Ships with **Sessions — Command reject**, **Job — Command reject**, **Storage — Connectivity**, and **Component — Server performance** | | | Subscription | Inbox | Sends the notification to the in-console inbox of the chosen recipients | | | Subscription | Receiver | The users or groups that receive that event, set with **Edit recipient** | | {% hint style="warning" %} Do not enable **Use SSL** and **Use TLS** together — pick the one your mail server supports. Use **Test connection** before saving; it exercises the current values without persisting them. {% endhint %} Approval notifications ride on this channel: when a user requests access the approvers are e-mailed, and when the request is decided the requester is notified. Neither happens if the mail server here is wrong. ## Storage **System settings › Storage**. Two independent stores, one tab each. | Tab | Field | What it does | Default | | --------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ | --------- | | Object storage | Name | Label for the backend | | | Object storage | Type | `Server` (local disk), `S3`, `Ceph`, `Swift`, `OSS`, `Azure`, `OBS`, `COS`, `SFTP`, or `Null` (discard) | | | Object storage | Connection fields | Per type: endpoint, bucket or container, access key, secret, region | | | Object storage | Default | Which backend receives new recordings. Only one at a time | `default` | | Object storage | Description | Free text | | | Command storage | Name, Type, connection fields | An external index for the text of executed commands. Empty by default, in which case commands stay in the local database | Empty | Two entries ship and cannot be deleted: **default**, the local filesystem of the server, and **null**, which discards recordings — useful for sessions that deliberately are not kept. Recordings are compressed by the solution before storage, on local disk and on external backends alike, without loss of replay fidelity. {% hint style="warning" %} Retention and storage are not the same lever. **Retentions › Session log** expires the *metadata* in the database; the lifetime of the recording *files* is whatever the bucket's own lifecycle policy says. Configure both, or you will keep paying for objects whose records are already gone — or worse, lose files whose records suggest they are still there. {% endhint %} ## Retentions **System settings › Retentions**. How many days each kind of record is kept before the nightly cleanup tasks delete it. Every field is an integer number of days and every one is required. | Section | Field | What it covers | Default | | ---------- | -------------------------------------------- | -------------------------------------------------------------------------- | ------- | | Log record | Login log retention days | Console authentications: successes, failures, lockouts, logouts | 180 | | Log record | Task log retention days | Runs of the system's own scheduled tasks | 180 | | Log record | Operate log retention days | Administrative changes to users, assets, permissions and settings | 180 | | Log record | Password change log keep days | Automatic credential changes on managed assets | 999 | | Log record | FTP log retention days | File transfers mediated by the solution | 180 | | Log record | Session log retention days | Session metadata: user, asset, start, end, duration, protocol | 200 | | Log record | Activity log retention days | General user activity in the console — queries, views, access to resources | 180 | | Database | Job execution retention days | Runs of the automation jobs against assets | 180 | | Database | Cloud sync task history retention days | Synchronisation runs against external sources | 180 | | Database | Change secret and push record retention days | Each rotation and push operation: asset, account, time, result | 180 | {% hint style="info" %} **Password change log keep days** defaults to 999 while everything else defaults to 180, and the difference is intentional. That log is what reconstructs who held which credential when, so it is the one record you do not want to be the first to expire. {% endhint %} A retention window is not retroactively recoverable: shortening one discards the history immediately, and a question asked outside the window cannot be answered afterwards. ## Components **System settings › Components**. The **Basic** tab holds global behaviour; the **Components** tab is a read-only list of the registered services. | Section | Field | What it does | Default | | ----------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------- | | Basic | Registration | Lets a newly installed component register itself with this instance. Required | Enabled | | SSH & Terminal Protocol | Client connection | Offers the user a native SSH client. With it off, terminal access goes only through the built-in web client | Enabled | | SSH & Terminal Protocol | Password | Allows password authentication to the terminal component. The managed secret is injected without being shown to the user | Enabled | | SSH & Terminal Protocol | Public key | Allows SSH public-key authentication to the terminal component | Enabled | | SSH & Terminal Protocol | Asset sorting | Order of the asset list the user sees: `Name` or `Address` | Name | | SSH & Terminal Protocol | Asset page size | Assets per page in that list. `Auto` sizes it to the window | Auto | | DB & Database Proxy | Database proxy | Enables the database connector, and with it native database clients. Off removes brokered database sessions from the whole platform | Enabled | {% hint style="warning" %} Turn **Registration** off once the components you need are registered. While it is on, anything that knows this instance's address can register itself as a component. Turn it back on only for the minutes it takes to add one. {% endhint %} The **Components** tab reports, per service, its name, current online sessions, CPU and memory usage, load status (`Normal`, `High load`, `Offline`), ID, type, and remote address. It has no editable fields. ## RemoteApp **System settings › RemoteApp**. Port policies, the rules that pick one, and the catalogue of published applications. A **TCP ports** policy sets the ports on which the connector *listens* for each protocol — the ports a user's client connects to on the solution, not the ports the solution uses to reach the asset. Those are on [Ports and protocols](/pam/reference/ports), and they are different numbers on purpose. | Section | Field | What it does | Default | | --------------- | ----------------- | ------------------------------------------------------------------------------------------- | ----------- | | TCP ports | Name | Label for the policy. Required | | | TCP ports | Asset | Binds the policy to one asset. Left empty, the policy is selected by IP source rule instead | | | TCP ports | HTTP port | `0` disables the protocol for this policy | 0 | | TCP ports | HTTPS port | `0` disables the protocol for this policy | 0 | | TCP ports | SSH port | Listener for brokered SSH sessions | 2222 | | TCP ports | RDP port | Listener for brokered RDP sessions | 3389 | | TCP ports | VNC port | Listener for brokered VNC sessions | 15900 | | TCP ports | MySQL port | Listener for the MySQL proxy | 33061 | | TCP ports | MariaDB port | Listener for the MariaDB proxy, separate so both engines can be served | 33062 | | TCP ports | PostgreSQL port | Listener for the PostgreSQL proxy | 54320 | | TCP ports | Redis port | Listener for the Redis proxy | 63790 | | TCP ports | SQLServer port | Listener for the SQL Server proxy | 14330 | | TCP ports | Oracle port range | Range reserved for Oracle connections, which use several ports at once | 30000–30030 | | TCP ports | Active | An inactive policy is never selected, even when bound to an asset | Active | | TCP ports | Description | Free text. Record which network segment the policy is for | | | IP source rules | Name | Label for the rule. Required | | | IP source rules | Priority | Evaluation order. **Lower is evaluated first** | 50 | | IP source rules | Asset IP | The asset addresses or CIDRs the rule covers. Required | | | IP source rules | Endpoint | Which TCP ports policy applies to them | | | IP source rules | Active | An inactive rule is skipped without being deleted | | | IP source rules | Description | Free text | | {% hint style="info" %} The non-standard listener ports are not arbitrary. `2222`, `15900`, `33061`, `54320`, `63790` and `14330` all sit beside the conventional port of the same protocol so that the listener does not collide with a service of the same kind running on the solution's own server. Oracle needs the **whole range** open between clients and the solution, not one port. {% endhint %} Selection works from the asset outwards: when a session starts, the solution looks for an active IP source rule whose **Asset IP** covers the target, and applies that rule's policy. If none matches, the **Default** policy applies. The **Virtual access applications** area, on the same screen, holds the catalogue of published applications, the machines they run on, and the application providers that deliver the sessions. Publishing machines are selected at random with a preference for the last one used; tag a machine on the asset to pin it. The account used on the publishing machine is, in order of preference, one named after the console user, a dedicated account for them, or a shared public account. ## System tools **System settings › Tools**. Network diagnostics run **from the solution's own server**, which is what makes them worth having: they answer whether the solution can reach an asset, which is a different question from whether your workstation can. | Field | What it does | Default | | -------------------- | ----------------------------------------------------------------------------- | ------- | | Tools in the cockpit | Global switch. Off removes the tools for everyone, whatever their permissions | Enabled | The tabs are **Ping**, **Telnet**, **Nmap**, **Tcpdump** and **Traceroute**. Each takes a destination and shows the raw command output; **Telnet** and **Nmap** also take ports, and **Tcpdump** takes an interface plus source and destination filters. **Address** is a read-only field that shows what a hostname resolved to, which makes it a quick DNS check from the server. Keep the switch on and restrict the tools by role instead. Nmap and Tcpdump are reconnaissance tools in the wrong hands, and captured packets deserve the same confidentiality as the assets they came from. ## Tenants **System settings › Tenants**. Each tenant is an isolated organization with its own assets, users, permissions, logs and settings; an administrator of one does not see another. | Field | What it does | Default | | -------------- | ----------------------------------------------------------------------------------- | ------- | | Name | Name of the tenant | | | Description | What it is for — a department, a branch, a customer | | | Administrators | The users who manage it | | | Members | The users who belong to it | | | Setting | Per-tenant parameters such as an exclusive authentication source and session policy | | The listing counts users, user groups, assets and asset authorizations per tenant. Two tenants ship: **DEFAULT**, which everything created without a tenant belongs to, and **SYSTEM**, which is used by the solution's own internal components and should not be edited. ## Areas with no configurable fields | Area | What it is instead | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Operations** | A read-only list of the solution's own scheduled tasks, with each one's queue, success count, cycle and next run. The system manages them; you consult them | | **Monitoring** | A live view of the task workers and queues, opened from Operations. Its value is that an offline worker means no automation is running at all | | **Licensing** | Licence details and import | ## Related pages * [Ports and protocols](/pam/reference/ports) — the ports used toward assets, as opposed to the listeners configured under RemoteApp * [Audit trail](/pam/administration/audit/audit-trail) — the records the Retentions settings expire * [The credential vault](/pam/administration/accounts/vault) — what the Account storage tab moves to an external vault * [Login policies](/pam/administration/access/login-policies) — per-user rules, as opposed to the global Security settings * [Session recordings](/pam/administration/audit/recordings) — what the Storage settings hold # Ports and protocols The default port each platform uses to reach an asset, and why the effective port is set per asset rather than globally. ## What this page covers The port the solution uses to reach an **asset**, per platform. This is the list a firewall request is written from. {% hint style="info" %} It does not cover the ports the solution itself listens on. Those depend on how the instance was deployed and belong with the deployment documentation. {% endhint %} ## How the port is decided Two levels, and confusing them causes most "the firewall is open but it still fails" tickets: | Level | What it holds | | ------------ | ---------------------------------------------------------------------------- | | **Platform** | The **default** port for each protocol. A suggestion inherited by new assets | | **Asset** | The **effective** port actually used for that asset | Changing the port on a platform does not move the assets already registered against it. Use **Sync protocols to assets** on the Platforms screen to push the change, or set the port on the individual asset. Any port is accepted. The defaults below are conventions, not constraints — which is what makes the solution workable in environments that do not run services where the internet expects them. ## Hosts | Platform | Protocols and default ports | | ------------- | -------------------------------------------------- | | Linux | SSH 22 · SFTP 22 · TELNET 23 · VNC 5900 · RDP 3389 | | Gateway | SSH 22 · SFTP 22 · TELNET 23 · VNC 5900 · RDP 3389 | | Unix | SSH 22 · TELNET 23 · VNC 5900 · RDP 3389 | | AIX | SSH 22 · TELNET 23 · VNC 5900 · RDP 3389 | | BSD | SSH 22 · TELNET 23 · VNC 5900 · RDP 3389 | | macOS | SSH 22 · TELNET 23 · VNC 5900 · RDP 3389 | | Windows | RDP 3389 · WinRM 5985 · SSH 22 · VNC 5900 | | Windows-RDP | RDP 3389 · WinRM 5985 · SSH 22 · VNC 5900 | | Windows-TLS | RDP 3389 · WinRM 5985 · SSH 22 · VNC 5900 | | RemoteAppHost | RDP 3389 · WinRM 5985 · SSH 22 | | Other | SSH 22 · SFTP 22 · TELNET 23 · VNC 5900 · RDP 3389 | ## Databases | Platform | Protocol and default port | | ---------- | ------------------------- | | Oracle | oracle 1521 | | MySQL | mysql 3306 | | MariaDB | mariadb 3306 | | PostgreSQL | postgresql 5432 | | SQLServer | sqlserver 1433 | | MongoDB | mongodb 27017 | | Redis | redis 6379 | | Redis6+ | redis 6379 | | ClickHouse | clickhouse 9000 | | DB2 | db2 50000 | | Dameng | dameng 5236 | ## Network devices All device platforms — General, Cisco, Huawei, H3C, and Fortinet — use **SSH 22** and **TELNET 23**. ## Cloud and web | Platform | Protocol and default port | | -------------- | ------------------------- | | Kubernetes | k8s 443 | | Vmware-vSphere | http 80 | | Website | http 80 | | ChatGPT | chatgpt 443 | ## Ports used by automations Automations reach the target over a **management** protocol, which is not necessarily the protocol users connect with: | Target | Management protocol | Port | | -------------------- | ------------------- | ---- | | Linux | SSH | 22 | | Windows | WinRM | 5985 | | Windows, alternative | OpenSSH | 22 | RDP is not a management protocol. An asset whose only registered protocol is RDP can host user sessions but cannot be reached by account collection or credential rotation. ## Related pages * [Platforms](/pam/administration/assets/platforms) — where the defaults come from * [Asset inventory](/pam/administration/assets/inventory) — where the effective port is set * [Database sessions](/pam/administration/sessions/database) * [Collect accounts from an asset](/pam/administration/accounts/discovery-of-accounts) * [Rotate credentials](/pam/administration/accounts/rotation) # Supported platforms A quick answer to "is my technology supported?" — the built-in platforms by category, with the non-obvious choices flagged and a pointer to the Platforms page for the detail. This page answers one question: **is there a built-in platform for the thing I want to protect?** It is a checklist, not a reference — the protocols, the default ports, and the selection criteria for each platform are on [Platforms](/pam/administration/assets/platforms), and the ports a firewall request is written from are on [Ports and protocols](/pam/reference/ports). A technology is supported when a platform exists for it, because the platform is what tells the solution which protocols the asset accepts and which automations can run against it. Anything else is registered against a custom platform, and still works — see [If yours is not listed](#if-yours-is-not-listed). ## Hosts | Platform | Note | | ----------------- | ----------------------------------------------------------------------------------------------------- | | **Linux** | Linux distributions in general | | **Gateway** | Same technical base as Linux, kept separate so that a jump host is visible as one in the inventory | | **Unix** | Generic Unix | | **AIX** | | | **BSD** | FreeBSD, OpenBSD, and derivatives | | **macOS** | Workstations and servers | | **Windows** | Servers and workstations. RDP serves graphical access, WinRM serves automations | | **Windows-RDP** | For hosts that require classic RDP negotiation, without TLS | | **Windows-TLS** | For hosts that require RDP over TLS | | **RemoteAppHost** | The host that publishes remote applications. It runs the applets and is not an ordinary access target | | **Other** | Hosts that fit none of the families above | {% hint style="info" %} The three Windows variants differ only in how RDP security is negotiated, which varies between server versions and configurations. When a graphical connection fails **during negotiation**, moving the asset between **Windows**, **Windows-RDP**, and **Windows-TLS** is the first thing to try — it is a platform choice, not a credential problem. {% endhint %} ## Databases | Platform | Note | | -------------- | -------------------------------------------------------- | | **Oracle** | | | **MySQL** | | | **MariaDB** | A MySQL fork, treated as its own platform | | **PostgreSQL** | | | **SQLServer** | Microsoft SQL Server | | **MongoDB** | | | **Redis** | Versions before 6 | | **Redis6+** | Version 6 and later, which have their own users and ACLs | | **ClickHouse** | | | **DB2** | IBM Db2 | | **Dameng** | DM database | {% hint style="warning" %} Choosing **Redis** for a Redis 6 or later server prevents login with a named credential, because per-user authentication only exists from version 6. Pick **Redis6+** for anything current. {% endhint %} Both a browser console and a native client — DBeaver, SQL Server Management Studio, Oracle SQL Developer, MongoDB Compass and others — can reach these. See [Database sessions](/pam/administration/sessions/database). ## Network devices **General**, **Cisco**, **Huawei**, **H3C**, and **Fortinet**, all reached by command line. **General** covers any device for which no specific platform exists. The vendor platforms are not cosmetic: they differ in terminal handling and command recognition, which is what makes command auditing and [command inspection](/pam/administration/access/command-filtering) accurate for that vendor's CLI. Use **General** only when there is no closer match. ## Cloud, web, and AI | Platform | Note | | ------------------ | --------------------------------------------------------------------------------------------- | | **Kubernetes** | Cluster access, with the panel reached through the web console | | **Vmware-vSphere** | VMware vSphere virtualization | | **Website** | A web application opened in a controlled browser with the credential typed in by the solution | | **ChatGPT** | Audited access to a generative AI service | {% hint style="danger" %} **Website** assets need an additional Windows machine to run the browser. No web session runs on the solution's own server — that is a deliberate security boundary. Without that machine a Website asset can be registered but no session will open. See [Web sessions](/pam/administration/sessions/web). {% endhint %} ## If yours is not listed Nothing is blocked by the absence of a built-in platform. In order of preference: 1. **Duplicate the closest built-in platform** and adjust its ports or disable a protocol. You keep the rest of its behaviour, which is why this is the recommended path. 2. **Use the generic platform for the family** — **Other** for a host, **General** for a network device. 3. **Create a platform** from scratch, when neither of the above fits. Custom platforms carry no **BUILT-IN** badge and, unlike the built-in ones, can be edited and deleted freely. What decides whether an asset can actually be managed is not the platform name but the protocol. An asset whose only registered protocol is RDP can host user sessions but cannot be reached by account collection or credential rotation, because those run over a management protocol — SSH or WinRM. ## Related pages * [Platforms](/pam/administration/assets/platforms) — every platform in detail, with its protocols and selection criteria * [Ports and protocols](/pam/reference/ports) — the default port per platform * [Asset inventory](/pam/administration/assets/inventory) — registering an asset against a platform * [Connection methods](/pam/administration/sessions/connection-methods) # Compliance mappings Every control each compliance package answers, and which operational report the package embeds as the evidence for it. ## What this page is Each of the seven compliance packages in [Reports](/pam/administration/audit/reports) opens with a control map: a table that pairs a framework control with the operational report that evidences it. The package then embeds those operational reports in full, in the same file. This page is that map, for all seven packages, so you can answer two questions without generating anything: * **Which controls does this package cover?** Read the framework's table below. * **Where does a control's evidence come from?** The right-hand column names the operational report, and [Reports](/pam/administration/audit/reports#operational-reports) says what that report contains. {% hint style="warning" %} This is a mapping of platform evidence to control identifiers. It is not an assessment, a score, or a certification, and the coverage below is not a claim that the control is satisfied — only that the platform produces records relevant to it. Controls a PAM cannot reach, such as network segmentation or physical security, are absent by nature. {% endhint %} Two operational reports are not cited by any package: **File transfer** and **Automation runs**. Generate those separately when an assessor asks for them. ## PCI-DSS v4.0 Eight controls, five reports. | Control | What it covers | Evidence report | | ------- | --------------------------------- | ------------------------- | | 8.2 | Unique user identification | Access and authentication | | 8.3 | Strong authentication and MFA | Access and authentication | | 7.2 | Access on a need-to-know basis | Credential retrieval | | 8.6 | System and application accounts | Credential retrieval | | 7.2.5 | Controlled privileged access | Session activity | | 10.2 | Access audit trails | Session activity | | 8.3.9 | Periodic credential rotation | Password rotation | | 10.2.1 | Logging of administrative actions | Configuration trail | ## SOC 2, Trust Services Criteria Seven criteria, five reports. | Criterion | What it covers | Evidence report | | --------- | -------------------------------------- | --------------------------- | | CC6.1 | Logical access controls | Access and authentication | | CC6.6 | Authentication | Access and authentication | | CC6.3 | Privileged access | Session activity | | CC7.2 | Activity monitoring | Session activity | | CC6.2 | Access provisioning and deprovisioning | Account and vault inventory | | CC7.3 | Security event trail | Configuration trail | | CC6.3 | Access approval, JIT | Approvals and JIT access | ## HIPAA Security Rule Five controls, four reports. | Control | What it covers | Evidence report | | ---------------- | ------------------------------------- | --------------------------- | | 164.308(a)(4) | Information access management | Account and vault inventory | | 164.312(a)(2)(i) | Unique user identification | Access and authentication | | 164.312(d) | Person or entity authentication | Access and authentication | | 164.312(b) | Audit controls | Session activity | | 164.312(b) | Recording and examination of activity | Configuration trail | ## ISO/IEC 27001:2022 Seven controls, five reports. The identifiers follow the 2022 Annex A. | Control | What it covers | Evidence report | | ------- | ------------------------------------ | --------------------------- | | A.5.15 | Access control | Account and vault inventory | | A.5.18 | Access rights | Account and vault inventory | | A.5.17 | Authentication information | Credential retrieval | | A.5.17 | Management of authentication secrets | Password rotation | | A.8.2 | Privileged access rights | Session activity | | A.8.15 | Logging | Session activity | | A.8.15 | Event logging | Configuration trail | ## LGPD, Lei 13.709/2018 Five articles, four reports. | Article | What it covers | Evidence report | | ------- | ------------------------------- | ------------------------- | | Art. 46 | Security measures on access | Access and authentication | | Art. 46 | Access control over data | Credential retrieval | | Art. 37 | Record of processing operations | Session activity | | Art. 37 | Record of operations | Configuration trail | | Art. 46 | Traceability | Configuration trail | ## NIST SP 800-53 Rev.5 Sixteen controls, eight reports. The widest of the seven packages. | Control | What it covers | Evidence report | | ------- | ------------------------------------------ | --------------------------- | | AC-2 | Account management | Account and vault inventory | | AC-2(3) | Disable inactive accounts | Account and vault inventory | | IA-2 | Identification and authentication of users | Access and authentication | | IA-2(1) | MFA for privileged access | Access and authentication | | AC-7 | Unsuccessful logon attempts | Access and authentication | | AC-6 | Least privilege | Credential retrieval | | IA-5 | Authenticator management | Credential retrieval | | AC-6(9) | Logging the use of privileged functions | Session activity | | AU-14 | Session audit | Session activity | | AU-6 | Audit record review and analysis | Commands and violations | | SI-4 | System monitoring | Commands and violations | | IA-5(1) | Password-based authentication | Password rotation | | AU-2 | Event logging | Configuration trail | | AU-12 | Audit record generation | Configuration trail | | AC-3 | Access enforcement | Approvals and JIT access | | AC-2 | Access approval and provisioning | Approvals and JIT access | ## CIS Controls v8 Twelve safeguards, eight reports. | Safeguard | What it covers | Evidence report | | --------- | ----------------------------------------------- | --------------------------- | | 5.1 | Account inventory | Account and vault inventory | | 5.3 | Disable dormant accounts | Account and vault inventory | | 6.3 | MFA for externally exposed applications | Access and authentication | | 6.5 | MFA for administrative access | Access and authentication | | 5.4 | Restrict admin privileges to dedicated accounts | Credential retrieval | | 6.8 | Role-based access control | Credential retrieval | | 8.5 | Collect detailed audit logs | Session activity | | 8.11 | Audit log review | Commands and violations | | 5.2 | Use unique and strong passwords | Password rotation | | 8.2 | Collect audit logs | Configuration trail | | 6.1 | Access granting process | Approvals and JIT access | | 6.2 | Access revocation process | Approvals and JIT access | ## Which report answers the most controls Read the other way round, so you know which report to reach for when a control is questioned. Across the seven packages the maps cite sixty controls in all: | Operational report | Controls it evidences, across all seven packages | | --------------------------- | ------------------------------------------------ | | Access and authentication | 12 | | Session activity | 11 | | Configuration trail | 9 | | Credential retrieval | 8 | | Account and vault inventory | 8 | | Approvals and JIT access | 5 | | Password rotation | 4 | | Commands and violations | 3 | | File transfer | 0 | | Automation runs | 0 | {% hint style="info" %} The report names above are the English names used throughout this wiki. The generated file labels its sections in Portuguese whatever the console language is, so **Access and authentication** appears in the file as `== Acessos & Autenticação ==`. See the known limitations in [Reports](/pam/administration/audit/reports#known-limitations). {% endhint %} ## Related pages * [Reports](/pam/administration/audit/reports) — generating these packages, and what each operational report contains * [Audit trail](/pam/administration/audit/audit-trail) — the records underneath every one of them * [Configuration fields](/pam/reference/configuration-fields) — the retention settings that bound how far back a report can reach # Glossary Every term this documentation uses, defined as DataDike PAM uses it, with a link to the page that documents each one. The words below mean specific things in this product, and a few of them mean something narrower than they do elsewhere in the industry. Where a term has a page of its own, the entry links to it. Two entries are worth reading before the rest, because mixing them up is the most common source of confusion: * **authorization** and **profile** are not the same control. A profile decides which console screens a person sees; an authorization decides which assets and accounts they may reach. An auditor can hold a powerful profile and no authorization at all. * **proxy** and **gateway** are two halves of one mechanism, not two mechanisms, and neither is the **broker**, which reverses the direction of the connection. {% hint style="info" %} These are used as acronyms throughout and are never expanded in running text: **A2A**, **API**, **LDAP**, **MFA**, **PAM**, **RDP**, **SFTP**, **SIEM**, **SSH**, **SSO**, **UEBA**. {% endhint %} ## Terms | Term | Definition | | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [**A2A**](/pam/administration/integrations/application-to-application) | Application-to-application access. The mechanism by which a tool, rather than a person, fetches a credential from the vault over the API — audited the same way a human session is | | [**account template**](/pam/administration/accounts/account-templates) | A reusable account definition, registered once and linked to as many assets as need it, so a shared credential such as a domain administrator is maintained in one place instead of one per asset | | [**anomaly**](/pam/administration/ueba/policy) | One detected departure from a user's baseline behaviour, recorded by UEBA with a risk score and a record of which mitigation was applied | | [**API**](/pam/reference/api) | Application programming interface. The REST interface the console itself uses, and through which external systems drive the solution | | [**approval**](/pam/administration/access/approvals) | A human decision required before something takes effect. An authorization can demand it before granting access, command inspection can hold a command pending it, and a login rule can require it for out-of-hours sign-in | | [**asset**](/pam/administration/assets/inventory) | Anything the solution brokers access to, and the destination of a session: a server, a network device, a database, a web application, a cloud host. An asset is never a credential. The menu calls the list **Assets**; the screen's own title is **Devices** | | **asset connect** | Interface label for a user opening a session on an asset, as opposed to signing in to the console. The rules that govern it live under **Policies › Asset connect** | | [**audit trail**](/pam/administration/audit/audit-trail) | The searchable records the solution writes for everything that happens through it — logins, sessions, commands, password changes, file transfers, and administrative changes | | [**authorization**](/pam/administration/access/authorizations) | The rule that grants access, joining who (users and groups), what (assets and accounts), and how (protocols, permitted actions, validity, whether approval is required). No access exists without one | | [**automatic mitigation**](/pam/administration/ueba/policy) | The master switch under which UEBA acts on its own when a risk score crosses the threshold set for an action — terminating a session, rotating credentials. With it off, detection records and alerts only | | [**baseline window**](/pam/administration/ueba/policy) | The number of days of history UEBA treats as a user's normal behaviour. Scores are unreliable until a full window has passed | | [**broker**](/pam/administration/connectivity/broker) | A service on a machine both sides can reach, which both the remote gateway and the solution dial out to, so that assets on networks that accept no inbound connection stay reachable | | **cluster** | An installation of the solution spread across several nodes for availability. Distinct from a Kubernetes cluster, which is a target registered for A2A access | | [**command inspection**](/pam/administration/access/command-filtering) | Interception of each command before it executes, and the decision to allow, block, hold for approval, or allow with an alert. Enforced on the server, and applied to automations as well as to interactive sessions | | [**connect method**](/pam/administration/sessions/connection-methods) | A rule controlling *how* a user may connect — which protocols and which clients — as opposed to which assets they may reach. Its only action is **Reject**: everything not denied stays available | | [**connector**](/pam/get-started/core-concepts) | An agent installed on a machine that has no gateway in front of it, so that the machine provides its own network path | | [**credential**](/pam/administration/accounts/managed-accounts) | An account on a target together with its secret. The user authenticates as themselves and the solution supplies the credential, so the two are never the same thing | | **DataDike PAM** | The name of the product. Never translated, abbreviated, or inflected | | **discover** | Interface label for the **Environment › Discover** area, where discovery accounts and sync policies are configured | | **discovery** | Finding assets or accounts that are not registered yet — from a cloud provider account, a virtualization platform, or an IP range — and filing what is found according to a policy | | **endpoint** | The address and port set a client uses to reach a component. A component can publish several — a default one for internal traffic, an external one, a private one — and the solution picks between them from the origin of the connection | | [**file transfer**](/pam/administration/sessions/file-transfer) | Moving files between a workstation and an asset through the solution rather than around it. Every upload and download is written to the audit trail with a retrievable copy of the file | | **folder** | A container in the asset tree, used both to file assets and as the target of authorizations and automations. Target selectors call the same object a **node** | | [**gateway**](/pam/administration/connectivity/gateways) | A jump host inside the asset network that the solution logs in to and forwards traffic through. It belongs to a proxy, and it is not the remote appliance that dials out to a broker — an asset uses one path or the other, never both | | [**just-in-time access**](/pam/administration/access/just-in-time) | Access granted on request for a limited period and withdrawn automatically when that period ends, in place of standing access. Abbreviated JIT | | [**LDAP**](/pam/administration/identities/ldap-and-ad) | Lightweight Directory Access Protocol. Used to authenticate console users against a directory such as Active Directory and to provision their records, group membership included | | [**live monitoring**](/pam/administration/audit/recordings) | Watching a session while it is still running, and pausing or terminating it. A recording, by contrast, is after the fact | | [**managed account**](/pam/administration/accounts/managed-accounts) | A credential on an asset that the solution stores, tests, rotates, and supplies on the user's behalf. A *common* account is registered and stays until removed; a *virtual* account is created by an authorization at connection time | | [**MFA**](/pam/administration/identities/mfa) | Multi-factor authentication. A second factor on top of the password, applied on whichever authentication method the user arrives by | | **node** | Two things, depending on the screen: a folder of the asset tree, as automation and rotation target selectors call it; and a machine of the installation itself, in a cluster | | [**PAM**](/pam/get-started/core-concepts) | Privileged access management. The discipline of brokering, recording, and controlling access to privileged accounts so that the person never holds the target credential | | [**platform**](/pam/administration/assets/platforms) | The technical model of an asset: which protocols it accepts, on which default port each one runs, whether the connection may pass through a gateway, and whether switching accounts after login is allowed. Every asset belongs to one | | [**profile**](/pam/administration/identities/roles) | Interface label for what a person may do inside the console — administer, audit, or only consume access. Not an authorization, and worth keeping distinct from it | | [**proxy**](/pam/administration/connectivity/proxy) | The zone record that groups the jump machines of one network and that assets are attached to — a data centre, a cloud, a VPC. The gateways live inside it | | [**RDP**](/pam/reference/ports) | Remote Desktop Protocol. The graphical protocol for Windows assets, on port 3389 by default | | [**report**](/pam/administration/audit/reports) | A packaged extract of the audit data, generated on demand or on a schedule and exported as PDF, XLSX, or CSV. For investigating one incident, search the audit trail instead | | [**risk score**](/pam/administration/ueba/risk-score) | The 0–100 severity rating UEBA assigns to each anomaly. It is not a percentage: it orders events for review and triggers mitigation when it crosses a threshold | | [**rotation**](/pam/administration/accounts/rotation) | Changing the secret of an account, storing the new value in the vault, and applying it to the dependencies registered against that credential so integrations do not break | | [**secret**](/pam/administration/accounts/vault) | The confidential value of an account — a password, an SSH key, a token, an access key, an API key. The account is the record; the secret is what the vault protects | | [**session**](/pam/get-started/core-concepts) | A connection opened through the solution. While it runs it can be watched and terminated; after it ends its recording stays in the audit trail. It is the unit auditing is built on | | [**session recording**](/pam/administration/audit/recordings) | The replayable capture of a finished session, played back as video with a timeline. Separate from the searchable list of commands typed in a session | | [**SFTP**](/pam/administration/sessions/file-transfer) | SSH File Transfer Protocol. The file transfer path on Linux assets, which by default uses the same port as SSH | | [**SIEM**](/pam/administration/audit/audit-trail) | Security information and event management. The external collector audit records are forwarded to, so the trail survives independently of the appliance | | [**SSH**](/pam/reference/ports) | Secure Shell. The terminal protocol for Linux, Unix, and network devices, on port 22 by default | | [**SSO**](/pam/administration/identities/sso) | Single sign-on. Console login delegated to a corporate identity provider over SAML2, OIDC, OAuth2, CAS, or Slack | | **tag** | A free label attached to an asset, account, template, or user, used to filter lists and to scope the rules that select by attribute | | [**template**](/pam/administration/accounts/account-templates) | Interface label for an account template. The menu is **Accounts › Templates** | | [**threshold**](/pam/administration/ueba/policy) | A numeric line that turns a measurement into an action: the risk score at or above which a session is terminated, or the count of failed logins that counts as a burst | | [**UEBA**](/pam/administration/ueba/policy) | User and entity behaviour analytics. The module that builds a baseline of how each user normally works, scores departures from it, and can mitigate them automatically | | [**user group**](/pam/administration/identities/users-and-groups) | A set of users, used as the subject of an authorization so that a rule is written once for a team instead of once per person | | [**user login**](/pam/administration/access/login-policies) | Interface label for a person signing in to the console, as opposed to asset connect. The rules that govern it live under **Policies › User login**, and its records are the Login log | | [**vault**](/pam/administration/accounts/vault) | Where the secrets of managed accounts are kept. Users open sessions without seeing them, automations read them to authenticate, and every access is recorded | ## Related pages * [Core concepts](/pam/get-started/core-concepts) — the same vocabulary as a chain of related objects rather than an alphabetical list * [Ports and protocols](/pam/reference/ports) * [Supported platforms](/pam/reference/supported-platforms) * [Configuration fields](/pam/reference/configuration-fields) # Release notes What this section records, how the entries are organised, and the version-specific items that change what you have to do during an upgrade. ## What this section is This section records features introduced and behaviour changed in DataDike PAM releases. Entries are grouped by year, then by month, and each one is dated. It is where the version-dependent facts live. Two kinds of entry change what you have to do rather than merely telling you what is new: * entries that state a **restart is required** * entries that record a capability **removed and later restored** Both kinds are on record, which is why the [Upgrade](/pam/deploy-operate/upgrade) page treats reading the notes between your installed version and your target version as a prerequisite rather than background reading. {% hint style="warning" %} **Treat this section as a record of notable changes, not as a complete changelog.** Only part of 2026 has entries, not every entry names a version number, and a release with no entry here is not evidence that nothing changed in it. Confirm version-specific behaviour with DataDike support instead of inferring it from a gap. {% endhint %} ## Planned | Release | Planned for | What changes | | ------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **6.0** | February 2027 | **SMS is removed as a multi-factor authentication method.** Accounts that use SMS as their second factor have to move to another method before upgrading | | **6.0** | February 2027 | **A native SAP platform**, with credential rotation and verification carried out over RFC, covering dialog users and the non-dialog account types (system, communication and service) | | **6.0** | February 2027 | **CrowdStrike Falcon as a risk signal.** Endpoint detections are read as an input to the access decision, so a privileged session opened from a host with an open detection can be blocked or sent for approval | {% hint style="warning" %} **This affects the MFA factor only.** SMS as a *notification* channel is not changed: approval requests and just-in-time requests can still be sent by SMS. What goes away is the option to receive the second-factor code by text message at login. Before upgrading to 6.0, move affected users to [another factor](/pam/administration/identities/mfa). A user left on SMS when the release lands has no second factor, and how that resolves depends on whether MFA is enforced for them. {% endhint %} Dates and contents of a planned release can change. ## Features introduced in 2026 | Entry | Date stated | Version stated | What it covers | | ------------- | ---------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | February 2026 | 11 February 2026 | — | Asset-level rule configuration, including Exclusion rules, which allows automation and notifications to be tailored per account or per asset group. Faster credential capture on Linux and on Unix platforms | | May 2026 | 04 May 2026 | — | Reliability and stability improvements to the upgrade process of the gateway VM, with reduced downtime between versions | | June 2026 | 13 June 2026 | 5.0.1 | Granular automation-task permissions: access to automation tasks can be granted through custom roles instead of full administrator privileges. Enforcement of TLS 1.3 between the Gateway VM and the server — **the entry states a restart is required** | | August 2026 | 18 August 2026 | v5.1.0 | Stability of Windows access for Cloud-hosted customers. Reinstatement of custom asset friendly names, which had been removed in error between 5.0 and 5.0.9 | ## The entries that affect an upgrade | Version or range | Item | Why it matters | | ----------------- | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | 5.0.1 | TLS 1.3 enforced between the Gateway VM and the server | The entry states a restart is required. Plan the window accordingly and confirm the gateway side supports TLS 1.3 | | 5.0 through 5.0.9 | Editing an asset to set a custom friendly name was removed in error | If you run a version in this range, the capability is absent. It is a known regression, not something to troubleshoot | | 5.1.0 | That capability reintroduced. Environments that had already renamed assets individually do not lose the customisation | The fix for the range above | {% hint style="info" %} The May 2026 entry is inconsistent about which component it describes: its heading refers to the Broker VM and its body to the Gateway VM. Both are upgraded on their own path, separate from the platform's, so confirm which one applies before planning around it. {% endhint %} ## Items recorded without enough detail to act on Two things in this section are worth knowing about but cannot be turned into an instruction: **Cloud-hosted Windows access and latency.** The August 2026 entry states that for customers hosted in the DataDike Cloud in Brazil, Argentina and Chile, UDP is carried inside the reverse proxy through an HTTPS tunnel served over TCP, and that this protocol change makes access sensitive to latency above 60 ms, which causes interruptions. The entry is headed as an improvement but describes the condition rather than stating what changed. If you are Cloud-hosted and seeing Windows sessions drop, round-trip latency to the hosting region is the first thing to measure. **Three further items in the same entry** — improved identity threat detection and response, a platform design refresh, and support for external AI models — are listed without detail that could be verified against the product. Confirm their scope and availability with support before relying on them. ## Related pages * [Upgrade](/pam/deploy-operate/upgrade) * [Back up and restore](/pam/deploy-operate/backup-and-restore) * [Monitoring and health](/pam/deploy-operate/monitoring) * [Core concepts](/pam/get-started/core-concepts) # DataDike SONAR documentation Everything needed to deploy agents, manage and monitor endpoints, and audit activity with DataDike SONAR. | Where to start | What it covers | | ---------------------- | ----------------------------------------------------------- | | **Get started** | Concepts, architecture, and your first device | | **Administration** | Day-to-day administration | | **Deploy and operate** | Install, update, and remove agents, and diagnose them | | **Reference** | API, permissions, script variables, and supported platforms | | **Release notes** | What changed in each release | # Get started | Page | What it covers | | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | [What is DataDike SONAR](/sonar/get-started/what-is-datadike-sonar) | What DataDike SONAR does, who works with it, and where its scope ends. | | [Architecture and components](/sonar/get-started/architecture) | The parts SONAR is made of, on the server and on each endpoint, how a command travels to a device and back, and what stops working when one part is down. | | [Core concepts](/sonar/get-started/core-concepts) | The vocabulary SONAR uses — clients, sites, devices, status, policies, checks, tasks, alerts, employees, roles — and how the objects relate. | | [A tour of the console](/sonar/get-started/console-tour) | How the console is laid out: the sidebar groups, the header menus, the Home dashboard, and the path from the clients overview to a device and its tabs. | | [Onboard your first device](/sonar/get-started/first-device) | From an empty console to a first device online: create a client and a site, generate the agent installer, run it, and confirm the device reports. | # What is DataDike SONAR What DataDike SONAR does, who works with it, and where its scope ends. Read this first if you are evaluating the product or new to the console. DataDike SONAR is an endpoint management platform. An agent installed on each Windows, Linux or macOS computer reports to a central server, and from one web console you monitor those computers, reach them remotely, run commands and scripts on them, keep them patched, and see how they are used. The server is operated by DataDike. You install, update and remove the agents on your own computers; everything else happens in the console. ## What it covers | Area | What you do with it | Where it lives in the console | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | Devices and agents | See every computer that runs the agent, grouped by client and site, with its status, last response, hardware and operating system | **Dashboard › Sysadmin** | | Inventory | Hardware, operating systems, network interfaces, storage and installed software across the fleet | **Devices › Asset Inventory**, **Observability › Softwares** | | Remote access | Take control of a Windows desktop, open a remote terminal, transfer files, list and end processes, and manage Windows services and event logs | **Take Control** on the device | | Automation | Run a command or a script on one device or many, schedule automated tasks, and apply the same checks and tasks to whole groups of devices through automation policies | Device actions, the **Tools** menu, **Management › Scripts** | | Monitoring and alerts | Checks for CPU, memory, disk, ping, services, event logs and scripts, and alert templates that decide who is told and what runs when a check fails | The device **Checks** tab, **Alerts** | | Patching | Scan Windows computers for updates, approve and install them, one device at a time or across the environment | **Devices › Windows Updates**, the device **Updates** tab | | User activity | Logon sessions, applications and websites in use, and idle time on Windows computers, per user and per day | **Observability › Users Behavior**, **Observability › Users Traces** | | Access policies | Windows logon time windows per device, site or client, enforced on the computer, with extension requests the end user sends and you approve | **Observability › Policies**, **Observability › Requests** | | People | The employees behind the Windows usernames, and the signed terms of use attached to them | **Management › Employees**, **Management › Terms** | | Audit | A record of who changed what in the console, who logged in, and which commands, scripts and remote sessions were run | **Reports & Audits › Audits** | User activity and access policies depend on the **productivity module**, a second service the agent installs on Windows computers. Linux and macOS computers run the agent only. ## Who uses it * **IT operators** watch device status, answer alerts, run scripts and open remote sessions. Most of their day is spent in **Sysadmin** and the device panel. * **Administrators** create clients and sites, define automation policies, alert templates and access policies, and decide what each console user may do in **Admin Center › Roles**. * **Managers** read user activity reports and approve or deny extension requests. * **End users** work on the managed computers. With the productivity module, their logon hours follow the access policies and they can ask for more time from the computer itself. One console serves several organizations. Each one is a **client**, divided into **sites**, and a console user can be limited to the clients and sites their role allows. See [Core concepts](/sonar/get-started/core-concepts). ## What it is not * **Not a discovery tool.** SONAR manages computers that run the agent. A device without the agent does not appear in the console. * **Not an antivirus or an EDR.** It does not scan files for malware or block threats. It can watch and act on a computer — a service check, a script — but threat detection is not its job. * **Not a mobile device manager.** Agents exist for Windows, Linux and macOS. Phones and tablets are out of scope. * **Not a server you run.** There is nothing for you to install on the SONAR server, and no page in this documentation asks you to. Settings that belong to the server itself are set up with DataDike implementation support. ## Related pages * [Architecture and components](/sonar/get-started/architecture) — the parts that make up SONAR and how a command reaches a device * [Core concepts](/sonar/get-started/core-concepts) — the vocabulary used in every screen * [A tour of the console](/sonar/get-started/console-tour) — where each thing lives * [Onboard your first device](/sonar/get-started/first-device) — from an empty console to a device online * [Supported platforms](/sonar/reference/supported-platforms) # Architecture and components The parts SONAR is made of, on the server and on each endpoint, how a command travels to a device and back, and what stops working when one part is down. SONAR has two halves. On the **server**, operated by DataDike, a set of services holds the data, serves the console and talks to the devices. On each **endpoint**, one or more services installed by the agent installer keep a connection to the server, report on the computer, and carry out what the console asks for. Knowing which part does what turns "SONAR is not working" into "remote desktop is down on this computer, everything else answers". {% hint style="info" %} This page is about the software that runs the product. The objects you manage — clients, sites, devices, policies — are in [Core concepts](/sonar/get-started/core-concepts). Installing agents belongs to Deploy and operate. {% endhint %} ## The components ### On the server | Component | What it does | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Console** | The web application you log in to. Everything you see and do in SONAR goes through it | | **API** | Serves the console and your integrations, authenticates every request, records changes in the audit trail, and receives the data agents send over HTTPS: check results, task results, script output, installed software, Windows updates, user activity | | **Messaging service** | Holds one persistent connection per agent. Commands travel to the device over it, and the agent's heartbeat and inventory reports travel back, to be written to the database as they arrive | | **Task service** | Runs the scheduled and background work: availability alerts and notifications, bulk actions, delivery of automated tasks to Windows computers, scheduled tasks on Linux and macOS, patch approval and installation schedules, automatic agent updates, distribution of access policies, and the figures behind the dashboards | | **Remote access service** | Carries remote desktop, remote terminal and file transfer sessions to the remote access agent on each device, and provides wake-on-LAN and the power history shown in the **Uptime** tab | | **Database** | Holds the configuration, the inventory, the history and the audit trail | These services run on the server that DataDike operates for you. How they are sized, backed up and updated is set up with DataDike implementation support. ### On the endpoint | Component | Platforms | Service name on the computer | What it does | | ----------------------- | --------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **SONAR agent** | Windows, Linux, macOS | `sonarrmm` (**Sonar Agent Service**) on Windows; `sonaragent` on Linux and macOS | Registers the computer, sends a heartbeat and inventory, runs checks, commands, scripts and tasks, scans for and installs Windows updates, and updates itself | | **Remote access agent** | Windows, Linux, macOS | **Mesh Agent** | Serves remote desktop, remote terminal and file transfer sessions. Installed by the agent installer | | **Productivity module** | Windows | `SonarProductivityService` (**Sonar Productivity Service**) | Records logon sessions, the applications and websites in use, and idle time, and enforces the access policies on the computer: blocks a logon outside the allowed window, warns before a session ends, and signs the user out when it does | Every connection is opened **from the endpoint to the server**, over HTTPS on port 443: the agent to the API address, and the remote access agent to the remote access address. Nothing on the network has to reach into the endpoint. See [Network requirements](/sonar/deploy-operate/network-requirements). ## How a command reaches a device Running a command on one device, from the **Send Command** action of the device panel: 1. **You submit the command in the console.** The API checks that your role grants the permission and gives you access to that device's client and site. 2. **The API writes a line in the device's History tab** and hands the command to the messaging service, addressed to that one agent. 3. **The messaging service delivers it** over the connection the agent keeps open. The agent runs the command in its own process. 4. **The agent replies** over the same connection, and also sends the output to the API, which stores it against the History line. 5. **The console shows the output** and the audit trail records who ran what, on which device. A script follows the same path. A bulk action from the **Tools** menu differs in one respect: the API does not wait for the devices. It queues the job, the task service sends it to every selected agent at once, and each device's output arrives in its own **History** tab as it finishes. Scheduled work runs the other way round. The agent asks the API, on its own schedule, which checks are due and sends back each result. Automated tasks on Windows are written into the computer's own task scheduler, which starts them at the planned time; on Linux and macOS, the task service starts them. In both cases the result comes back to the API and shows in the device's tabs. ## When a device is offline A device's status is the age of its last heartbeat, which the agent sends about once a minute while it is connected. There is no separate "disconnected" signal: a device that stops reporting keeps its last status until the offline threshold passes. The thresholds are in [Core concepts](/sonar/get-started/core-concepts#device-status). What that means for the work you send: | You send | While the device is offline | | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | A command, a script, a reboot, a shutdown, a process list, a service action | Needs the agent connected. A single-device action fails with a message such as `Unable to contact the agent`. A bulk action is sent once; a device that is offline at that moment does not run it later | | Checks | The agent fetches the checks that are due when it runs its next cycle, so they resume on their own when the device is back | | Automated tasks for Windows | Created, changed or removed on the computer the next time it is online. Tasks already on the computer keep their schedule | | Access policies | Held for the device. The productivity module receives the current version when it reconnects, applies it, and confirms it | | Remote desktop, terminal, file transfer | Needs the remote access agent connected, shown as **Remote Online** in the device panel | ## What stops when a part is unavailable | Unavailable | What stops | What keeps working | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Console or API** | The console, the integrations, and everything agents send over HTTPS: results, script output, inventory updates | The agents keep running on the computers | | **Messaging service** | Commands, scripts, reboots, process, service and event log views, check runs on demand. Heartbeats stop being recorded, so devices move to offline once the threshold passes | Remote desktop, terminal and file transfer, which use the remote access service | | **Task service** | Availability alerts and email or SMS notifications, bulk actions, automatic agent updates, patch schedules, Linux and macOS scheduled tasks, delivery of access policy changes, and the refresh of the dashboard figures | Actions on a single device from its panel, which go straight through the API | | **Remote access service** | Remote desktop, remote terminal, file transfer, wake-on-LAN, the **Uptime** tab | Everything that goes through the agent | | **Database** | Everything | Nothing on the server side | | **SONAR agent on a device** | That device stops reporting and accepting commands, and goes offline | Remote desktop may still answer if the remote access agent is running | | **Remote access agent on a device** | Remote desktop, terminal and file transfer for that device. The panel shows **Remote Offline** | Everything that goes through the SONAR agent. With the agent online, **Restart Remote Service** in the device panel asks the agent to restart the remote access agent | | **Productivity module on a device** | User activity for that computer, and enforcement of access policies on it | Everything that goes through the SONAR agent | ## Why some figures lag Screens that summarise the whole fleet do not count devices each time you open them. The task service calculates those figures in the background, and the **Home** dashboard cards are recalculated every five minutes. A device that has just come online appears in the **Sysadmin** device list as soon as you reload it, and in the Home counts within a few minutes. ## Common errors | Symptom | Cause | Fix | | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `Unable to contact the agent` when sending a command | The agent is not connected to the messaging service | Check **Agent Status** and **Last Response**. If the device is off or offline, wait for it to come back; the command is not queued | | A bulk action reports that it will run, but some devices have no result in **History** | Those devices were offline when the job was sent | Run the action again on those devices once they are online | | **Take Control** is disabled and the panel shows **Remote Offline** | The remote access agent on the device is not connected | If the device is online, use **Restart Remote Service**; otherwise wait for the device to return | | The device list shows a device as online, but it was switched off an hour ago | The status is the age of the last heartbeat, and the offline threshold has not passed yet | Read **Last Response**, which shows the actual time of the last contact | | A new device is in the device list but not yet in the Home counts | The Home figures are recalculated every five minutes | Wait a few minutes and refresh the Home dashboard | ## Related pages * [Core concepts](/sonar/get-started/core-concepts) — the objects the components act on * [A tour of the console](/sonar/get-started/console-tour) — where each screen lives * [Network requirements](/sonar/deploy-operate/network-requirements) — what the endpoints must be able to reach * [The productivity module](/sonar/deploy-operate/productivity-module) * [Troubleshoot agents](/sonar/deploy-operate/troubleshooting) # Core concepts The vocabulary SONAR uses — clients, sites, devices, status, policies, checks, tasks, alerts, employees, roles — and how the objects relate. Almost every screen in the console is a list of one of the objects below. Learning how they fit together makes the rest of this documentation read quickly, and a few of them are easy to confuse — those are called out at the end. ## The chain, in one sentence A **device** runs the **agent** and belongs to a **site** of a **client**; the **automation policies** that reach it through that client and site give it its **checks** and **tasks**; a failing check raises an **alert**, handled as its **alert template** says; and every change made in the console is written to the **audit trail** under the name of the **SONAR user** who made it. ## How devices are organised ### Client The top level of the tree: one organisation whose computers you manage. Every site, and therefore every device, belongs to exactly one client. Clients are listed in the **Clients** group of the **Sysadmin** sidebar and managed from **Management › Clients**. ### Site A subdivision of a client — an office, a branch, a department. A device belongs to exactly one site. The agent installer is always generated for one site, so the site decides where a new device appears. ### Device and agent A **device** is a computer that runs the **agent**. The device is the record in the console; the agent is the software on the computer. Each device has a **type** — **workstation** or **server** — chosen when the agent is installed. The type decides which automation policy a client or site gives the device, since each of them can hold one policy for workstations and one for servers. Devices appear in **Dashboard › Sysadmin**, and selecting one opens the device panel with its tabs. See [The device list](/sonar/administration/devices/device-list). ## Device status The status of a device is the time since the agent's last heartbeat, which it sends about once a minute while connected. **Last Response** in the device list shows that time. | Status | Meaning | Default threshold | | ----------- | --------------------------------------------------- | ------------------------ | | **online** | The agent has reported within the offline threshold | — | | **offline** | No heartbeat for longer than the offline threshold | 12 hours (720 minutes) | | **overdue** | No heartbeat for longer than the overdue threshold | 30 days (43,200 minutes) | Both thresholds are set per device in the device's **Edit** dialog, as **Offline after (minutes)** and **Overdue after (minutes)**. A device becoming overdue is what raises an availability alert, when the device or its alert template asks for one; the alert is resolved when the device reports again. The counters on the **Home** dashboard and in the **Clients overview** group devices by fixed bands of time since their last contact — under 12 hours, over 12 hours, over 24 hours, over 7 days, over 30 days — and count devices in maintenance mode on their own. The Clients overview also counts archived devices separately. ### Maintenance mode A switch on a device, or on every device of a site or a client at once (**Enable Maintenance Mode** in the device menu or in the client tree). While a device is in maintenance mode, no alerts are raised for it. Its checks and tasks keep running, and it is counted under **In Maintenance** rather than by status. Use it for planned work, so that a server you are rebooting does not page anyone. ### Archived device **Archive Agent** tells the agent on the computer to uninstall itself, which happens if the device is online at that moment, and keeps the device's record and history in the console, counted under **Archived**. No alerts are raised for an archived device. Unarchiving it does not reinstall the agent; to manage that computer again, install the agent on it. ## Automation ### Automation policy A named set of **checks** and **tasks** — and optionally a patch policy and an alert template — that you define once and assign to many devices. Policies are managed in **Management › Automations** and assigned with **Assign Automation Policy**, on a device, a site or a client. A device receives, from the most specific level to the most general: 1. the policy assigned to the device itself; 2. the site's **Workstation Policy** or **Server Policy**, depending on the device type; 3. the client's workstation or server policy; 4. the default workstation or server policy, set in **Admin Center › Settings** under **Defaults**. **Block policy inheritance** on a device, a site or a client stops the levels above it from applying. When a device's own check and a policy check measure the same thing — the same disk, the same service — the device's check wins, unless the policy is **Enforced**, in which case the policy's check wins. Tasks are not merged: the device runs its own tasks and those of every policy that reaches it. See [Automation policies](/sonar/administration/automation/automation-policies). ### Check A measurement the agent takes on a schedule, with a pass or fail result: **CPU Load Check**, **Memory Check**, **Disk Space Check**, **Ping Check**, **Windows Service Check**, **Event Log Check**, **Script Check**. A check that fails a set number of times in a row raises an alert. Results are in the device's **Checks** tab. See [Checks](/sonar/administration/automation/checks). ### Task An automated task: a sequence of commands and scripts that the agent runs on a schedule — **Daily**, **Weekly**, **Monthly**, **Run Once** — or when a check fails (**On check failure**), once when the task first reaches a device (**Onboarding**), or only when you start it (**Manual**). Results are in the device's **Tasks** tab. See [Automated tasks](/sonar/administration/automation/automated-tasks). ### Script A reusable piece of code kept in **Management › Scripts** — PowerShell, Batch, Python, Shell, Nushell or Deno — that you run on a device, on many devices, as a check, or as a step of a task. See [Script library](/sonar/administration/automation/scripts). ## Alerts ### Alert A record that something needs attention: a device became overdue, a check failed, or a task failed. Each alert has a severity — **Informational**, **Warning** or **Error** — and stays open until it is resolved, either on its own when the check passes again or the device returns, or by hand. The bell in the header shows the most recent active alerts. ### Alert template The rules that decide what happens when an alert opens and when it resolves: who receives an email or an SMS, whether the alert shows in the console, and which script or web request runs as an action. Templates are managed from the **Alerts** button in the header and assigned to a client, a site or an automation policy, or set as the default in **Admin Center › Settings**. The template in effect for a device is the most specific one: the device's policy, then the site, then the client, then the default. At the site and client levels, a template carried by the assigned automation policy comes before one assigned directly. See [Alerts and alert templates](/sonar/administration/automation/alerts). ## People and access ### SONAR user A person who logs in to the console. SONAR users are managed in **Admin Center › Users**, sign in with a password and a second factor, and have one **role** each. Everything they change is written to the audit trail under their name. ### Role What a SONAR user may do in the console: a set of permissions, grouped as **Agents**, **System**, **Automation & Tasks**, **Policies** and so on, plus **Client & Site Access** — the **Allowed Clients** and **Allowed Sites** the role is limited to. An empty list means all clients, or all sites, are allowed. **Super User** grants everything. Roles are managed in **Admin Center › Roles**. See [Roles and permissions](/sonar/administration/identities/roles). ### Employee A person who uses the managed computers — not someone who logs in to the console. SONAR creates an employee record the first time the productivity module sees a new Windows username in a session, and you complete it with a name, position, department and the sites the person works at. One employee can have several usernames. Employees are in **Management › Employees**, and the signed **terms** of use attached to them in **Management › Terms**. See [Employees](/sonar/administration/employees/employees). ### Access policy A set of Windows logon time windows — for example Monday to Friday, 08:00 to 18:00 — assigned to devices (one device, a site, a client, or all devices) and to users (a username, a username pattern, or the employees of a site). For those users on those devices, the productivity module blocks a logon outside the window, warns before the window ends, and signs the user out when it does, according to the policy's settings. Users that no policy covers are not affected. Access policies are in **Observability › Policies**. See [Access policies](/sonar/administration/access/access-policies). ### Extension request A request an end user sends from a Windows computer for more time outside their window. It appears in **Observability › Requests**, where you approve or deny it; an approved request gives that user a temporary allowance. See [Extension requests](/sonar/administration/access/requests). ## Audit trail The record of what happened through the console: objects created, changed and deleted, with their values before and after; logins; commands and scripts run; bulk actions; remote sessions. It is in **Reports & Audits › Audits**, and the records for one device are in its **Audits** tab. The device's **History** tab holds the output of the commands, scripts and tasks run on it. See [Audit trail](/sonar/administration/audit/audit-trail). ## Distinctions worth getting right **SONAR user is not employee.** A SONAR user logs in to the console and acts on devices. An employee uses a managed computer and never logs in to the console. The same person can be both, with two unrelated records. **Automation policy is not access policy.** An automation policy gives devices checks and tasks — it is about looking after the computer. An access policy decides when people may log on to Windows — it is about the user. They are managed in different places (**Management › Automations** and **Observability › Policies**) and never affect each other. **Check is not task.** A check measures and reports pass or fail; it can raise an alert. A task acts: it runs commands and scripts. The two meet when a task is set to run **On check failure**, which is how a failing check can fix its own cause. **Role is not client scope alone.** A role both grants actions and limits them to its allowed clients and sites. Giving someone access to a client does not let them run scripts there unless the role also grants **Run Scripts**. **Offline is not overdue.** Offline means the device has not reported for a while — a laptop that is switched off at night. Overdue means it has been gone long enough to raise an availability alert. ## Related pages * [Architecture and components](/sonar/get-started/architecture) — the software that runs these objects * [A tour of the console](/sonar/get-started/console-tour) — where each object lives * [Onboard your first device](/sonar/get-started/first-device) — the vocabulary in practice * [Clients and sites](/sonar/administration/devices/clients-and-sites) * [Glossary](/sonar/reference/glossary) # A tour of the console How the console is laid out: the sidebar groups, the header menus, the Home dashboard, and the path from the clients overview to a device and its tabs. The console is one web application with two fixed parts — a **sidebar** on the left that takes you to each screen, and a **header** along the top that holds the actions you start from anywhere — and a work area between them. Which sidebar entries and menu items you see depends on your role. An entry your role does not grant is either missing or shown greyed out with the tooltip `You don't have permission for this action`. If something in this tour is not in your console, check your role in [Roles and permissions](/sonar/administration/identities/roles) before looking anywhere else. ## The sidebar The sidebar is divided into groups. Each group opens and closes with a click on its name, and the button at the left of the header collapses the whole sidebar to icons. | Group | Entries | What you do there | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Dashboard** | **Home**, **Sysadmin** | Home is the fleet at a glance. Sysadmin is where devices are listed and managed, and where most daily work happens | | **Clients** | **All Clients**, then each client, expandable to its sites | Appears only inside Sysadmin, once you have opened the device list. Filters the list to one client or site, and holds the actions for that client or site | | **Devices** | **Asset Inventory** › **Overview**, **Devices**, **Hardware**, **Operating Systems**, **Network**, **Storage**; **Windows Updates** | The hardware and software inventory of the fleet, and patching across all Windows machines | | **Observability** | **Policies**, **Requests**, **Users Behavior**, **Users Traces**, **Geolocation**, **Softwares** | Access policies and extension requests; user activity per person and as a timeline; device locations; installed software across the fleet | | **Management** | **Employees**, **Terms**, **Scripts** | The people behind the Windows usernames, their signed terms of use, and the script library | | **Reports & Audits** | **Reports**, **Audits** | Report templates and their output; the audit trail of everything done in the console | | **Admin Center** | **Users**, **Roles**, **Settings** | Console users, the roles that decide what they may do, and the settings of your installation | **Settings** is divided into tabs: **General**, **Mail Server**, **SMS**, **Mesh Central**, **Custom Fields**, **Key Store**, **URL Actions**, **Web Hooks**, **Retention** and **API Keys**. The **Mesh Central** tab connects the console to the remote access service and is maintained with DataDike implementation support. ## The header From left to right, after the sidebar button: | Element | What it does | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Search functionality...** | Finds a console action by name — *Install Agent*, *Bulk Script*, *Create Site* — and opens it. Results are grouped by category, and actions your role does not grant are shown disabled | | **Alerts** | Opens the alert templates: the rules for who is notified and what runs when an alert opens or resolves | | **Agents** | **Install Agent** — generate an installer for a site. **Deployments** — the installer links created for sites. **Pending Actions** — scheduled reboots and other actions queued for devices | | **Tools** | **Bulk Command**, **Bulk Script**, **Bulk Patch Management** — run a command, a script, or a patch scan or installation on many devices at once, chosen by client, site or selection | | **Management** | **Create** › **Client**, **Site**, **User**. **Clients** — manage clients and sites. **Automations** — automation policies. **Roles** — roles and permissions | | Bell | The most recent active alerts, with the number active. Each one can be snoozed or resolved from the list; clicking an alert opens the alerts overview | | Your name | **Reset Password** and **Reset 2FA** for your own account | | Logout icon | Ends your session | ## Home **Dashboard › Home** is the landing page after login. Its figures are recalculated in the background every few minutes; the arrow at the top right reloads the page. | Card | What it shows | | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Devices Status** | **Online**, **In Maintenance**, **Overdue**, **Offline for 12+ hours**, **Offline for 24+ hours**, **Offline for 7+ days** and **Total**. Clicking a tile opens Sysadmin filtered to those devices | | Device carousel | One device at a time — hostname, status, operating system, logged-in user, IP address, site, and whether it needs a reboot or is in maintenance mode. It advances on its own; the search box finds a device by any of those values | | **Storage Overview — Disks Near Capacity** | How many devices have a disk above 90% used, out of the total monitored, and the devices with the highest usage. Clicking a hostname opens it in Sysadmin | | **Devices Per CPU** | Device count per processor model, filtered by **All**, **Intel**, **AMD** or **Apple** | | **Devices per OS** | Device count per operating system version, filtered by **All**, **Windows**, **Linux** or **Mac** | | **Servers x Workstations** | Total servers and servers online; total workstations and workstations online | ## Sysadmin: from client to device ### Clients overview **Dashboard › Sysadmin** opens on the **Clients overview** — *Device health snapshot per client*. There is one card per client, plus **All clients** with the organisation totals. Each card shows the number of devices and seven counters: **Online < 12h**, **Offline > 12h**, **Offline > 24h**, **Offline > 7d**, **Overdue > 30d**, **In maintenance** and **Archived**. **Search client...** narrows the cards. Clicking a card opens the device list for that client, or for all clients. ### The device list The list is titled **SYSADMIN — Endpoint monitoring and management**. Above it: * **Search devices...** — search by hostname, description, operating system, client or site name, or IP address; * **Filters** — **Availability** (**Online**, **Offline**, **Overdue**, **Offline 12+ hours**, **Offline 24+ hours**, **Offline 7+ days**, **Maintenance Mode**), **Device Type** (**Servers**, **Workstations**) and **Last Seen**; * **New Agent** — opens the agent installer; * the menu at the right — choose the columns to show. Active filters appear as chips under the toolbar, with **Clear Filters** to remove them all. The list is paged, with 10, 25, 50 or 100 devices per page. The columns are **Hostname**, **IP**, **Agent Status**, **Last Response**, **OS**, **Type**, **Checks Status**, **Client**, **Site**, **Public IP**, **Description**, **User**, **Patches Pending**, **Pending Actions**, **Needs Reboot**, **Boot Time**, **First Seen**, **SMS Alert**, **Email Alert** and **Dashboard Alert**. See [The device list](/sonar/administration/devices/device-list) for what each one holds. In the **Clients** group of the sidebar, right-clicking a client or a site opens its menu: **Edit**, **Delete**, **Add Site** (clients), **Install Agent** (sites), **Enable Maintenance Mode**, **Assign Automation Policy**, **Assign Alert Template**, **Run URL Action** and **Run Checks**. ### The device panel Selecting a row opens the device panel under the list, on its **Home** tab; drag the bar between them to resize. At the top of the Home tab, a bar shows the status — **Online**, **Offline** or **Overdue** — and the remote access status — **Remote Online** or **Remote Offline** — followed by the hostname, **Maintenance Mode** when it is on, and the agent version. On the right of that bar: * **Take Control** — opens the remote window for the device, with **Take Control** (Windows desktop), **Terminal**, **File Browser** and **Processes**, plus **Services** and **Logs** on Windows; * **User Behavior** — the activity of the user logged in to the device; * **Other actions** — the device menu, also opened by right-clicking the row. The device menu holds **Take Control**, **Edit**, **Pending Agent Actions**, **Send Command**, **Run Script**, **Run Favorited Script**, **Enable Maintenance Mode**, **Archive Agent**, **Patch Management** › **Install Patches Now**, **Run Patch Status Scan**, **Run Checks**, **Wake-Up (WoL)**, **Assign Automation Policy**, **Reboot** › **Now**, **Later**, **Shutdown** and **Remove Agent**. The panel's tabs: | Tab | What it holds | | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Home** | **Hardware Details** — system, model, serial number, processor, operating system and install date, memory and disks, graphics, network with MAC address, public and LAN IP — plus **Storage Devices** with the use of each volume, and **Health & Monitoring** with the device's checks | | **Location** | The positions the device has reported, on a map | | **Uptime** | When the device was on and off, over time | | **Checks** | The checks that apply to the device, from its own settings and from automation policies, with their latest result | | **Tasks** | The automated tasks that apply to the device, with their last run and output | | **Updates** | Windows updates found on the device, their approval and installation state | | **Software** | Software installed on the device | | **History** | Commands, scripts and tasks run on the device, with their output | | **Notes** | Free notes about the device | | **Terms** | Signed terms of use attached to the device | | **Assets** | The detailed hardware inventory the agent reports | | **Debug** | Debug log entries recorded for this device | | **Audits** | The audit trail entries for this device | ## Where each thing lives | Thing | Where | | -------------------------------- | ------------------------------------------------------------ | | Client, site | **Management › Clients**; **Management › Create** | | Device, device actions | **Dashboard › Sysadmin** | | Agent installer | **Agents › Install Agent**; **New Agent** in the device list | | Automation policy | **Management › Automations** | | Alert template | **Alerts** in the header | | Active alerts | The bell in the header | | Script | **Management › Scripts** | | Bulk command, script, patching | **Tools** | | Windows updates across the fleet | **Devices › Windows Updates** | | Access policy | **Observability › Policies** | | Extension request | **Observability › Requests** | | Employee, terms of use | **Management › Employees**, **Management › Terms** | | Console user, role | **Admin Center › Users**, **Admin Center › Roles** | | Audit trail | **Reports & Audits › Audits** | ## Common errors | Symptom | Cause | Fix | | ----------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | | A sidebar entry or menu item is missing or greyed out | Your role does not grant it | Check the role in **Admin Center › Roles** | | The **Clients** group is not in the sidebar | It appears only inside Sysadmin, after you open the device list from a client card | Open **Dashboard › Sysadmin** and click a client card or **All clients** | | A device you expected is not in the list | A filter chip is active, or you opened a single client | Use **Clear Filters**, or pick **All Clients** in the sidebar | | **Take Control** is disabled | The remote access agent on the device is not connected | See [Remote control](/sonar/administration/remote-access/remote-control) | ## Related pages * [Core concepts](/sonar/get-started/core-concepts) — what each object on these screens is * [Onboard your first device](/sonar/get-started/first-device) — these screens used in order * [The device list](/sonar/administration/devices/device-list) * [Device details](/sonar/administration/devices/device-details) * [Roles and permissions](/sonar/administration/identities/roles) # Onboard your first device From an empty console to a first device online: create a client and a site, generate the agent installer, run it, and confirm the device reports. ## What this is and when to use it A device appears in SONAR once the agent is installed on it, and the agent is always installed into a **site** of a **client**. This page takes you through the whole path once — client, site, installer, installation, verification — so that you know each screen before you deploy agents at scale. ## Before you start * A SONAR user whose role grants **Manage Clients** and **Manage Sites** (to create the client and site), **Install Agents** (to generate the installer) and **List Agents** (to see the device in Sysadmin). If your role is limited to some clients, a client you create is added to your role's **Allowed Clients**. * One computer running a supported version of Windows, Linux or macOS, and an account with administrator rights on it (root on Linux and macOS). See [Endpoint requirements](/sonar/deploy-operate/requirements). * That computer can open outbound HTTPS connections on port 443 to your SONAR addresses. See [Network requirements](/sonar/deploy-operate/network-requirements). ## Steps 1. Open **Management › Create › Client**. 2. In **Name**, type the client's name, for example `CLIENT-A`. 3. In **Default first site**, type the name of its first site, for example `SITE-01`, and click **Save**. The client and its site are created together. 4. To add more sites later, open **Management › Create › Site**, choose the **Client**, type the **Name**, and save. 5. Open **Agents › Install Agent**. The **Add an agent** window opens. 6. Choose the **Client** and the **Site** the device belongs to. 7. Choose the **Operating system**, the **Agent type** — **Workstation** or **Server** — and the **Architecture** of the computer. 8. On Windows, review the **Optional features** and choose the **Installation method**. **Dynamic (.exe)** is the simplest. 9. Leave **Enable token expiration (hours)** off for a first test, or turn it on and set how many hours the installer stays valid. 10. Click the button at the bottom of the window — for example **Download Windows installer (.exe)** — and take the file or the command to the computer. 11. Run the installer on the computer with administrator rights. The steps for each system are in [Install the agent on Windows](/sonar/deploy-operate/install-agent-windows), [Install the agent on Linux](/sonar/deploy-operate/install-agent-linux) and [Install the agent on macOS](/sonar/deploy-operate/install-agent-macos). 12. In the console, open **Dashboard › Sysadmin** and click the card of your client in the **Clients overview**. 13. Find the device by its hostname, or type it in **Search devices...**, and select the row. {% hint style="info" %} If the console has no client at all yet, opening **Dashboard › Sysadmin** shows **Initial Setup** instead of the Clients overview. It creates the first client and site in one form: fill in **Add Client** and **Add Site**, choose the **Default timezone for agents**, and click **Finish**. Then continue from step 5. {% endhint %} ## What you should see * After **Save**, the message `CLIENT-A was added`, and the client appears as a card in the **Clients overview**. A site added on its own returns `Site SITE-02 was added!`. * With **Dynamic (.exe)**, a message that the installer for your client and site will now be downloaded, whether it expires, and that no command line arguments are needed. The file is named after the client, the site, the agent type and the architecture, for example `sonar-clienta-SITE-01-workstation-amd64.exe`. * With the other methods, a script to download or a command to copy. * In Sysadmin, the client card counts one device, and the device list shows a row for the new computer. ## How to verify it worked In **Dashboard › Sysadmin**, on the device's row: * **Agent Status** shows **ONLINE**. * **Last Response** shows a time from the last minute or two, and **First Seen** shows when the agent registered. * **Client**, **Site** and **Type** match what you chose in the installer. Select the row. On the device panel's **Home** tab: * the bar at the top shows **Online** and, once the remote access agent has connected, **Remote Online**; * **Hardware Details** is filled in — model, processor, operating system, memory, network — within a few minutes of the installation. On Linux and macOS, fields the system does not report show `Not available`. Then open **Reports & Audits › Audits**: there is an **Agent Install** entry for the device's hostname. On the computer itself, the agent service is running: **Sonar Agent Service** (`sonarrmm`) on Windows, `sonaragent` on Linux and macOS. The **Home** dashboard counts the new device within a few minutes, when its figures are next recalculated. ## Common errors | Symptom | Cause | Fix | | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | **Create** › **Client**, **Install Agent** or **New Agent** is greyed out with `You don't have permission for this action` | The role lacks **Manage Clients**, **Manage Sites** or **Install Agents** | Ask an administrator to grant the permission in **Admin Center › Roles** | | `client with this name already exists.` | Client names are unique across the console | Choose another name, or add a site to the existing client | | `Client name cannot contain the \| character` or `Site name cannot contain the \| character` | The name contains a vertical bar | Remove the character | | The download button stays disabled | No client or site is selected | Choose both in the **Add an agent** window | | `Please enter a valid number of hours` | Token expiration is on with an invalid number of hours | Enter a whole number of hours, or turn expiration off | | `Installer token has expired. Please generate a new one.` on the computer | The installer was generated with an expiration that has passed | Generate a new installer | | `Old installer detected` on the computer | The installer was generated before the agents on the server were updated | Generate a new installer | | `Existing installation found` on a Windows computer | The agent is already installed on it | Remove the existing agent first — see [Remove agents](/sonar/deploy-operate/remove-agents) — then run the installer again | | The installation finished, but no device appears | The computer cannot reach the SONAR addresses on port 443 | Check [Network requirements](/sonar/deploy-operate/network-requirements) and [Troubleshoot agents](/sonar/deploy-operate/troubleshooting) | | The device appears but shows **Remote Offline** | The remote access agent has not connected yet | Wait a few minutes; if it stays offline, see [Remote control](/sonar/administration/remote-access/remote-control) | ## Field reference ### Create Client | Field | What it does | Accepted values | Default | | ---------------------- | -------------------------------------------------------------------------------------------------------- | --------------------------------- | --------- | | **Name** | The client's name, shown in the tree, the cards and every list | Required. Unique. No vertical bar | — | | **Default first site** | The name of the site created together with the client | Required. No vertical bar | — | | **Custom Fields** | Values for the client custom fields, when any are defined in **Admin Center › Settings › Custom Fields** | Depends on the field | Per field | ### Create Site | Field | What it does | Accepted values | Default | | ----------------- | ------------------------------------------------------- | --------------------------------------------------- | --------- | | **Client** | The client the site belongs to | An existing client | — | | **Name** | The site's name | Required. Unique within the client. No vertical bar | — | | **Custom Fields** | Values for the site custom fields, when any are defined | Depends on the field | Per field | ### Add an agent | Field | What it does | Accepted values | Default | | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------- | | **Client** | The client the new device belongs to | A client your role allows | — | | **Site** | The site the new device belongs to | A site of the chosen client | — | | **Operating system** | The system the installer is built for | **Windows**, **Linux**, **macOS** | **Windows** | | **Agent type** | Whether the device is a workstation or a server. Decides which workstation or server automation policy applies to it | **Workstation**, **Server** | **Workstation** | | **Architecture** | The processor architecture of the computer | Windows: **64-bit**, **32-bit**. Linux: **64-bit**, **32-bit**, **ARM 64-bit**, **ARM 32-bit**. macOS: **Intel 64-bit**, **Apple Silicon** | **64-bit** (**Intel 64-bit** on macOS) | | **Optional features** › **Sessions** | Windows. Installs the productivity module, which records user activity and enforces access policies | On, off | On | | **Optional features** › **Geolocation** | Windows. The device reports its position, shown in the **Location** tab and in **Observability › Geolocation** | On, off | On | | **Optional features** › **Remote access** | Windows. Turns on Windows Remote Desktop on the computer | On, off | On | | **Optional features** › **Ping** | Windows. Allows the computer to answer ping through the Windows firewall | On, off | On | | **Optional features** › **Disable sleep/hibernate** | Workstations. Turns off sleep and hibernation so the device stays reachable. Applies on Windows | On, off | On | | **Installation method** | Windows. How the installer is delivered: **Dynamic (.exe)**, a ready-to-run installer; **PowerShell**, a script; **Manual**, a command to run yourself. Linux gets an install script (`.sh`) and macOS a command, with no choice to make | **Dynamic (.exe)**, **PowerShell**, **Manual** | **Dynamic (.exe)** | | **Enable token expiration (hours)** | Limits how long the installer can register new devices. Off, the installer does not expire | Off, or a number of hours | Off; 24 hours when turned on | ## Related pages * [Clients and sites](/sonar/administration/devices/clients-and-sites) * [Install the agent on Windows](/sonar/deploy-operate/install-agent-windows) * [Deploy agents at scale](/sonar/deploy-operate/mass-deployment) * [The device list](/sonar/administration/devices/device-list) * [Troubleshoot agents](/sonar/deploy-operate/troubleshooting) # Administration | Page | What it covers | | -------------------------------------------------------- | -------------- | | [Devices](/sonar/administration/devices) | | | [Remote access](/sonar/administration/remote-access) | | | [Automation](/sonar/administration/automation) | | | [Patch management](/sonar/administration/patching) | | | [Software](/sonar/administration/software) | | | [User activity](/sonar/administration/user-activity) | | | [Access control](/sonar/administration/access) | | | [Employees and terms](/sonar/administration/employees) | | | [Users and identities](/sonar/administration/identities) | | | [Audit](/sonar/administration/audit) | | | [Settings](/sonar/administration/settings) | | # Devices | Page | What it covers | | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | [The device list](/sonar/administration/devices/device-list) | Find a device in Dashboard › Sysadmin: the clients overview, search, filters, columns and status, the action menu, and the Edit form. | | [Device details](/sonar/administration/devices/device-details) | The device panel below the list: header, status pills and the thirteen tabs, plus maintenance mode and archiving. | | [Clients and sites](/sonar/administration/devices/clients-and-sites) | Create, rename and delete clients and sites, move devices between sites, and how clients and sites tie into installers, policies and roles. | | [Asset inventory](/sonar/administration/devices/asset-inventory) | Devices › Asset Inventory: the fleet-wide overview and the device, hardware, operating system, network and storage lists built from agent reports. | # The device list Find a device in Dashboard › Sysadmin: the clients overview, search, filters, columns and status, the action menu, and the Edit form. ## What this is and when to use it **Dashboard › Sysadmin** is where every device with a SONAR agent is listed. It opens on a per-client health overview; picking a client opens the device list, titled **SYSADMIN — Endpoint monitoring and management**. From the list you find a device, read its status at a glance, open its details panel, act on it from the action menu, and change its settings with **Edit**. Use it whenever the question starts with a device: is it online, when did it last answer, who is logged in, does it need a reboot, which site is it in. ## Before you start * A role with **List Agents** (**Admin Center › Roles**, group **Agents**). The list shows only the devices of the clients and sites your role allows. * **Edit Agent** to use **Edit**, maintenance mode and archiving. The other actions of the menu have their own permissions, listed in [Actions on a device](#actions-on-a-device). * At least one device with the agent installed. See [Onboard your first device](/sonar/get-started/first-device). ## Steps 1. Open **Dashboard › Sysadmin**. The **Clients overview** appears, with one card per client and an **All clients** card with the organization totals. 2. Click a client card, or **All clients**. The device list opens with a **Client** filter chip above it. 3. To narrow the list to one site, expand the client in the **Clients** group of the sidebar and click the site. 4. Type in **Search devices...** and press Enter, or click the magnifier. 5. Click **Filters** to filter by availability, device type or last seen, then click **Apply**. 6. Click a column header to sort by that column. Click it again to reverse the order. 7. Click a row. The details panel below the list loads that device. 8. Right-click the row to open the action menu for that device. ## What you should see The list shows 10 rows per page by default; the selector above the table switches between 10, 25, 50 and 100, and **Page 1 of N** with the arrow buttons moves between pages. Search, filters and sorting apply to the whole list, not only to the page on screen. Every active filter appears as a chip above the table — **Client**, **Site**, **Availability**, **Type**, **Last seen**, and the sort order as **Order By Hostname (ASC)**. Each chip has an `x` to remove it; **Clear Filters** removes all of them, including the search text. When a list loads, the first row is selected and the details panel shows it. **No devices found.** means nothing matches the current client, search and filters. The console remembers the last client you opened. The next time you open **Dashboard › Sysadmin** in the same browser it goes straight to that client's devices; remove the **Client** chip to return to the overview. ## How to verify it worked * **Finding a device**: the chips above the table say exactly which client, site and filters produced the list. If a device you expect is missing, remove chips one at a time until it appears. * **Editing a device**: after **Save** the console shows `Agent was edited!` and the row reflects the new site, type or description. The change is recorded in **Reports & Audits › Audits** as a **Modify** action on object **Agent**, with your username and the values before and after. ## The clients overview The first screen of **Dashboard › Sysadmin** is titled **Clients overview — Device health snapshot per client**. Each card shows the client name, its number, the total of devices, and seven counters. Hover a counter to see its name. | Counter | Devices it counts | | -------------- | --------------------------------------------- | | Online < 12h | Checked in within the last 12 hours | | Offline > 12h | Last check-in between 12 and 24 hours ago | | Offline > 24h | Last check-in between 24 hours and 7 days ago | | Offline > 7d | Last check-in between 7 and 30 days ago | | Overdue > 30d | Last check-in more than 30 days ago, or never | | In maintenance | Devices in maintenance mode | | Archived | Archived devices | The five time-based counters leave out devices in maintenance mode and archived devices, which have their own counters. The windows are fixed and do not depend on each device's **Offline after** and **Overdue after** settings. **Search client...** filters the cards by client name or number. ## Columns Every column can be hidden or shown from the **⋮** button at the right of the toolbar (**Columns**). The choice is kept in your browser. | Column | What it shows | | --------------- | ------------------------------------------------------------------------------------------------------------ | | # | Row number across pages | | Hostname | Device name, with a server or workstation icon | | IP | Local IPv4 addresses reported by the agent; the public IP when there are none | | Agent Status | `online`, `offline` or `overdue` — see [Status](#status) | | Last Response | Date and time of the agent's last check-in | | OS | Operating system name and version | | Type | `server` or `workstation`, as set in **Edit** | | Checks Status | `Passing`, or the number of checks failing, warning and info — for example `1 failing / 0 warning / 0 info` | | Client | Client the device belongs to | | Site | Site the device belongs to | | Public IP | Address the device uses to reach SONAR | | Description | Free text set in **Edit** | | User | User logged in on the device. When no one is logged in and the device is online, the last user who logged in | | Patches Pending | `Yes` when the device has approved Windows updates not yet installed | | Pending Actions | Number of queued actions, such as a scheduled reboot | | Needs Reboot | `Yes` when the operating system reports a pending reboot | | Boot Time | Time since the last boot, for example `3 days ago` | | First Seen | When the agent registered with SONAR | These columns sort: **Hostname**, **IP**, **Agent Status**, **Last Response**, **OS**, **Type**, **Client**, **Site**, **Public IP**, **User**, **Boot Time** and **First Seen**. ## Status The agent checks in about once a minute. Each check-in updates **Last Response**, and the status is the age of that last check-in compared with two times set per device in **Edit**: | Status | Rule | Default | | --------- | ------------------------------------------------------------------------------------------------------------ | ----------------------- | | `online` | Last check-in newer than **Offline after** | 720 minutes (12 hours) | | `offline` | Older than **Offline after**, newer than **Overdue after**. A device that never checked in is also `offline` | — | | `overdue` | Older than **Overdue after** | 43200 minutes (30 days) | A device that is switched off keeps showing `online` until **Offline after** has passed. Lower **Offline after** on devices where you need to know sooner. `overdue` is the status that raises an availability alert, when overdue alerts are enabled for the device — see [Alerts and alert templates](/sonar/administration/automation/alerts). ## Search and filters **Search devices...** matches, in any part of the text: hostname, description, operating system, platform, type, client, site, public and local IP addresses, logged-in and last logged-in user, and CPU model. A date typed as `dd/mm` or `dd/mm/yyyy` matches devices whose last check-in, first seen or boot date falls on that day. The words `server`, `desktop` and `notebook` on their own list the devices of that hardware category. **Filters** opens **Filter Devices**: | Section | Option | Devices listed | | ------------ | ----------------------------------------------------------------- | ------------------------------------------------------------------------------ | | Availability | All | No availability filter | | | Online | Checked in within the last 12 hours | | | Offline | Status `offline`, by each device's own **Offline after** and **Overdue after** | | | Overdue | Last check-in more than 30 days ago | | | Offline 12+ hours | Last check-in between 12 and 24 hours ago, or never | | | Offline 24+ hours | Last check-in between 24 hours and 7 days ago | | | Offline 7+ days | Last check-in between 7 and 30 days ago | | | Maintenance Mode | Devices in maintenance mode | | Device Type | All, Servers, Workstations | By the **Type** set in **Edit** | | Last Seen | Any time, Last 1H, Last 3H, Last 12H, Last 24H, Last 7D, Last 30D | Last check-in inside that window, counted back from now | | | Custom... | Last check-in between two dates you pick | Except **Offline** and **Maintenance Mode**, the availability options leave out devices in maintenance mode and archived devices. **Clear** resets the three sections and reloads the list. ## Actions on a device Right-click a row, or use the **⋮** button in the details panel header, to open **Agent Actions** for that device. An item you lack the permission for is greyed out and says `You don't have permission for this action`. | Action | What it does | Permission | | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | | Take Control | Opens the remote access window for the device in a new browser tab | Use Mesh | | Edit | Opens the Edit form — see [Edit a device](#edit-a-device) | Edit Agent | | Pending Agent Actions | Lists the actions queued for the device, such as scheduled reboots, with **Cancel Action** | Edit Agent, List Pending Actions | | Send Command | Runs a one-off command on the device | Send Command | | Run Script | Runs a script from the library on the device | Run Scripts | | Run Favorited Script | Submenu with your favorited scripts | Run Scripts | | Enable Maintenance Mode / Disable Maintenance Mode | Stops the device from raising alerts while you work on it — see [Device details](/sonar/administration/devices/device-details#maintenance-mode) | Edit Agent | | Archive Agent / Unarchive Agent | Archives the device after you type `yes` — see [Device details](/sonar/administration/devices/device-details#archive-a-device) | Edit Agent | | Patch Management › Run Patch Status Scan | Asks the device to scan for Windows updates | Manage Windows Updates | | Patch Management › Install Patches Now | Installs the approved Windows updates now | Manage Windows Updates | | Run Checks | Runs the device's checks now | Run Checks | | Wake-Up (WoL) | Sends a Wake-on-LAN request to the device | Send Wake-on-LAN | | Assign Automation Policy | Assigns a policy directly to the device, or blocks inheritance | Manage Policies, Edit Agent | | Reboot › Now | Restarts the device after a confirmation | Reboot Agents | | Reboot › Later | Schedules a restart at a date and time in the device's time zone | Reboot Agents | | Shutdown | Shuts the device down after you type `yes` | Reboot Agents | | Remove Agent | Uninstalls the agent and deletes the device from SONAR. Asks for a **Reason**, stored in the audit record | Uninstall Agents | **Remove Agent** checks first whether the device answers. If it does not, the console warns that the agent will need to be uninstalled manually on the computer and asks whether to continue. See [Remove agents](/sonar/deploy-operate/remove-agents). Double-clicking a row opens **Edit**. ## Edit a device 1. Right-click the row and choose **Edit**, or double-click the row. 2. On **General**, change the fields you need — see the field reference below. 3. On **Custom Fields**, fill the values of the device custom fields. The tab lists every field created for agents in **Admin Center › Settings › Custom Fields**, and says so when there are none. 4. On **Patches**, set the device's Windows update approval and schedule — see [Patch approval policy](/sonar/administration/patching/patch-policy). 5. **Automation Policies** is read-only: it shows the policies that apply to the device, its alert template, and the effective patch policy. 6. Click **Save**. Changing **Site** moves the device to that site, with the policies and alert template that come with it. ## Common errors | Symptom | Cause | Fix | | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | A device is missing from the list | A chip is still filtering it out, or your role does not include its client or site | Click **Clear Filters**. If it is still missing, check the role's clients and sites in **Admin Center › Roles** | | An action is greyed out with `You don't have permission for this action` | Your role lacks the permission in the table above | Ask for the permission to be added to your role | | A switched-off device still shows `online` | **Offline after** has not passed since the last check-in | Wait, or lower **Offline after** for that device | | `Minimum is 15 seconds`, `Minimum is 2 minutes` or `Minimum is 3 minutes` under a field in **Edit** | The value is below the range the form accepts | Enter a value inside the range in the field reference | | **Remove Agent** says the agent is offline | The device did not answer | Continue only if you can uninstall the agent on the computer by hand | | The list opens straight on one client | The console restored the last client you opened | Remove the **Client** chip to return to the overview | ## Field reference **Edit › General** | Field | What it does | Accepted values | Default | | ---------------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------- | ---------------------- | | Site | Site the device belongs to. Changing it moves the device | Any site you can see | Site chosen at install | | Type | Server or workstation. Decides which policies apply and how the device is counted | `server`, `workstation` | Chosen at install | | Description | Free text shown in the **Description** column and searchable | Up to 255 characters | Empty | | Timezone | Time zone used for the device's schedules, such as **Reboot › Later** | Any time zone, or empty to follow the global default | Global default | | Device ownership | Whether the organization owns or leases the device | **Owned**, **Leased** | **Owned** | | Leased Reference | Contract or asset reference of a leased device | Up to 200 characters | Empty | | Run checks every (seconds) | How often the agent runs the device's checks | 15 to 86400 | 120 | | Offline after (minutes) | Time without a check-in after which the device shows `offline` | 2 to 9999998 | 720 | | Overdue after (minutes) | Time without a check-in after which the device shows `overdue` | 3 to 9999998 | 43200 | | Get overdue email alerts | Sends an email when the device becomes overdue | On, off | Off | | Get overdue sms alerts | Sends an SMS when the device becomes overdue | On, off | Off | | Get overdue dashboard alerts | Shows an alert in the console when the device becomes overdue | On, off | Off | An alert template applied to the device can send overdue alerts even when these three boxes are off. ## Related pages * [Device details](/sonar/administration/devices/device-details) — the panel below the list * [Clients and sites](/sonar/administration/devices/clients-and-sites) * [Custom fields](/sonar/administration/settings/custom-fields) * [Alerts and alert templates](/sonar/administration/automation/alerts) * [Remote control](/sonar/administration/remote-access/remote-control) # Device details The device panel below the list: header, status pills and the thirteen tabs, plus maintenance mode and archiving. ## What this is and when to use it When you select a device in **Dashboard › Sysadmin**, its details open in the panel below the list. The panel header tells you at a glance whether the agent and the remote access agent are reachable, and the tabs hold everything SONAR knows about the device: hardware, disks, checks, tasks, Windows updates, installed software, command history, notes, signed terms, location and logs. Use it to answer a question about one device, or to act on it without leaving the list. ## Before you start * A role with **List Agents**. Each tab also needs the permission of what it shows — see the [Tabs](#tabs) table. * The device selected in the list — see [The device list](/sonar/administration/devices/device-list). ## Steps 1. Open **Dashboard › Sysadmin** and pick a client. 2. Click the device's row. The panel loads it on the **Home** tab. 3. Drag the bar between the list and the panel to give the panel more room. The console keeps the size in your browser. 4. Click a tab to open it. Each tab loads its data when you open it. 5. To act on the device, use the buttons at the right of the header or the **⋮** menu (**Other actions**). ## What you should see The header shows, from left to right: | Element | What it means | | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Refresh icon | Asks the agent to report its system information now and reloads the panel | | **Online**, **Offline** or **Overdue** | Status of the SONAR agent — see [Status](/sonar/administration/devices/device-list#status) | | **Remote Online**, **Remote Offline** or **Remote Unknown** | Status of the remote access agent on the device, which **Take Control** depends on | | Hostname | Name of the device | | **Maintenance Mode** | Shown only while the device is in maintenance mode | | Version | Version of the SONAR agent | | **Take Control** | Opens the remote access window in a new browser tab. Disabled while the remote status is offline | | **User Behavior** | Opens **Recent user activity**, a side panel with the latest activity of the user logged in on the device, and **View full behavior** to open it in **Observability › Users Behavior** | | **⋮** (**Other actions**) | The same action menu as right-clicking the row — see [Actions on a device](/sonar/administration/devices/device-list#actions-on-a-device) | Below the header, the **Home** tab opens. ## How to verify it worked * **Fresh data**: click the refresh icon in the header. The console shows `Agent WMI data refreshed successfully` and the **Home** cards reload with what the agent just reported. `Unable to contact the agent` means the agent did not answer within 20 seconds. * **Maintenance mode or archive**: the header shows the **Maintenance Mode** pill, or the action menu now offers **Unarchive Agent**. Both changes are recorded in **Reports & Audits › Audits** as a **Modify** action on object **Agent**, and in the device's own **Audits** tab. ## Tabs | Tab | What it shows and what you can do | Permission | | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | Home | Hardware, storage, check health and custom fields — see [Home](#home) | List Agents | | Location | The device's reported positions on a map, with **Location History** grouped by day and the address of each point. Windows **1h**, **3h**, **12h**, **24h** (default), **7D**, **30D**, or **Custom range** with **Start** and **End**. Positions exist only for devices installed with location collection — see [Geolocation](/sonar/administration/user-activity/geolocation) | View Geolocation | | Uptime | The last seven days, one bar per day: **Powered on** in green, **Other states** in grey, and the daily totals. Hover a segment to see its start, end and duration. The data comes from the remote access service | Use Mesh | | Checks | The device's checks, including those inherited from policies, with their status, **Last Run** and **More Info**. **New** adds a check; **Run Checks Now** and **Reset All Checks Status** act on all of them; each check has **Edit**, **Delete**, **Reset Check Status** and **Show Run History**. See [Checks](/sonar/administration/automation/checks) | List Checks; Manage Checks and Run Checks to change or run them | | Tasks | The device's automated tasks with **Sync Status**, **Last Run Time**, **Schedule** and **Assigned Check**. **Add Task** creates one; each task has **Run task now**, **Edit** and **Delete**. See [Automated tasks](/sonar/administration/automation/automated-tasks) | List Tasks; Manage Tasks and Run Tasks to change or run them | | Updates | Windows updates found on the device, with **Severity**, **KB** and **Installed On**. Right-click an update to set it to **Approve**, **Ignore**, **Inherit** or **Do Nothing**. **Run Update Scan** and **Install Approved Updates** work only while the device is online. See [Updates on a single device](/sonar/administration/patching/device-updates) | Manage Windows Updates | | Software | Installed programs with **Name**, **Publisher**, **Version**, **Size** and **Install Date**, and **Search software...**. The refresh button asks the device for its current list; **Install Software** installs a package. See [Software inventory](/sonar/administration/software/software-inventory) | List Software; Manage Software to refresh or install | | History | Commands and scripts run on the device, with **Time**, **Action**, **Status**, **Script/Command**, **Initiated By** and **Output**, and a search box | List Agent History | | Notes | Free-text notes about the device, with **Date**, **User** and **Note**. **Add Note** creates one; each note has **Edit** and **Delete** | List Notes; Manage Notes to add, edit or delete | | Terms | Terms of use signed for this device, with who added each one and when. **View** opens a term; **Upload Term** attaches a new one. See [Terms of use](/sonar/administration/employees/terms) | Manage Terms to upload | | Assets | The hardware inventory reported by the agent, in thirteen sub-tabs: **Operating System**, **CPU**, **Memory**, **USB**, **Bios**, **Disks**, **Computer System**, **Motherboard**, **Computer System Product**, **Network Config**, **Graphics**, **Monitors** and **Network Adapters**. **Copy to Clipboard** copies the content of a sub-tab | List Agents | | Debug | Debug log entries for the device, newest first, up to the latest 1000. Filter by level (**Info** by default, **Warning**, **Error**, **Critical**) and by type (**Agent Issues**, **Windows Updates**, **System Issues**, **Scripting**) | View Debug Logs | | Audits | The audit trail filtered to this device: who did what on it, and when. See [Audit trail](/sonar/administration/audit/audit-trail) | View Audit Logs | **Updates**, **Software** and **Assets** apply to Windows devices. On Linux and macOS devices they show `Only supported for Windows Devices`. ### Home | Card | Contents | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Hardware Details › System | **Laptop** or **Desktop**, **Model**, and **Serial Number** when reported | | Hardware Details › Processor | CPU model; `2x` before the name when there are two processors | | Hardware Details › Operating System | Name and version, and **Install Date** when reported | | Hardware Details › Memory & Storage | **RAM** in GB, one line per physical disk, and **Graphics** | | Hardware Details › Network | **MAC Address** of the active adapter, **Public IP** and **LAN IP**, with a **Connected** badge | | Storage Devices | One card per volume: file system, percentage used, **Total**, **Used** and **Free** | | Health & Monitoring | Number of checks passing, failing, warning and info. With no checks, **No Active Checks** and **Configure Checks**, which opens the **Checks** tab | | Custom Fields | The device's custom field values that are filled in, except fields set to be hidden from the summary — see [Custom fields](/sonar/administration/settings/custom-fields) | Hardware details come from the inventory the agent reports about once an hour; disk usage is reported more often. The refresh icon in the header asks for a new report at once. ## Maintenance mode Maintenance mode silences a device while you work on it. While it is on, the device raises no alerts: an overdue device, a failing check or a failing task creates no alert in the console, sends no email or SMS, and runs no alert action. It changes nothing on the endpoint — the agent keeps checking in and running its checks and tasks. 1. Open the action menu of the device (right-click the row, or **⋮** in the panel header). 2. Choose **Enable Maintenance Mode**. The console confirms with `Maintenance mode was enabled on WS-0001`. 3. When the work is done, choose **Disable Maintenance Mode**. A device in maintenance mode shows the **Maintenance Mode** pill in the panel header, is counted under **In maintenance** in the clients overview, and is listed by the **Maintenance Mode** option of **Filters**. To switch a whole client or site at once, right-click it in the sidebar — see [Clients and sites](/sonar/administration/devices/clients-and-sites). Changing a device requires **Edit Agent**; changing a whole client or site requires **Run Bulk Operations** and **Edit Agent**. ## Archive a device Archiving takes a device out of service while keeping its record in SONAR. {% hint style="warning" %} **Archive Agent** sends the uninstall command to the agent and removes the device from remote access. The agent is removed from the endpoint if the device is online when you archive it. **Unarchive Agent** does not reinstall it. {% endhint %} 1. Open the action menu of the device and choose **Archive Agent**. 2. Type `yes` and click **Archive**. An archived device stays in the list, counted under **Archived** in the clients overview and left out of the time-based counters and of every availability filter except **Offline**. It raises no alerts. To bring it back, choose **Unarchive Agent**, type `yes` and click **Unarchive**. This clears the archived state of the record. To monitor the endpoint again, install the agent on it again — see [Onboard your first device](/sonar/get-started/first-device). To remove a device for good instead, use **Remove Agent** — see [Remove agents](/sonar/deploy-operate/remove-agents). ## Common errors | Symptom | Cause | Fix | | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | **Take Control** is disabled | The remote access agent on the device is offline (**Remote Offline**) | Check that the device is on and the remote access agent service is running on it | | `Unable to contact the agent` after the refresh icon | The agent did not answer within 20 seconds | Check the device's status. An `offline` device cannot answer | | `Only supported for Windows Devices` | **Updates**, **Software** and **Assets** apply to Windows | Use **Home** for the hardware of Linux and macOS devices | | **Run Update Scan** is disabled with `This machine must be online to run actions` | The device is not online | Wait for it to check in | | **Location** is greyed out with `You don't have permission for this action` | Your role lacks **View Geolocation** | Ask for the permission to be added to your role | | **Uptime** says `No timeline data available` | The remote access service has no power history for the device, or your role lacks **Use Mesh** | Check **Remote Online** in the header and your role | | **Location** says `No location data available for this time range` | The device reported no position in that window, or it was installed without location collection | Widen the window, or see [Geolocation](/sonar/administration/user-activity/geolocation) | | A tab stays empty | Your role lacks that tab's permission | Check the [Tabs](#tabs) table | ## Related pages * [The device list](/sonar/administration/devices/device-list) * [Remote control](/sonar/administration/remote-access/remote-control) * [Checks](/sonar/administration/automation/checks) * [Updates on a single device](/sonar/administration/patching/device-updates) * [Geolocation](/sonar/administration/user-activity/geolocation) # Clients and sites Create, rename and delete clients and sites, move devices between sites, and how clients and sites tie into installers, policies and roles. ## What this is and when to use it Every device in SONAR belongs to one **site**, and every site belongs to one **client**. A client is usually a customer or a business unit; a site is a location, a department or any group of devices inside it. The pair decides where the device appears in **Dashboard › Sysadmin**, which automation policies and alert template it inherits, and which users can see it, because roles are limited by client and site. Use this page to set up the structure before installing agents, and to keep it tidy afterwards: rename, add a site, move devices, delete what is no longer used. ## Before you start * A role with **List Clients** and **List Sites** to see them, **Manage Clients** to create, rename or delete clients, and **Manage Sites** for sites (**Admin Center › Roles**, group **Clients & Sites**). * **Edit Agent** to move a device to another site, plus **Run Bulk Operations** to move many at once. * The names you want to use. A client name must be unique; a site name must be unique within its client. Neither may contain the `|` character. ## Steps **Create a client** 1. Open the **Management** header menu and choose **Create › Client**. 2. Fill **Name** and **Default first site**. A client always starts with one site. 3. Fill the client custom fields, if any are listed. 4. Click **Save**. The console confirms with `CLIENT-A was added`. **Create a site** 1. Choose **Management › Create › Site**, or right-click the client in the **Clients** group of the sidebar on **Dashboard › Sysadmin** and choose **Add Site**. 2. Pick the **Client** and fill **Name**. 3. Fill the site custom fields, if any are listed. 4. Click **Save**. The console confirms with `Site SITE-01 was added!`. **Rename a client or a site** 1. Right-click it in the **Clients** group of the sidebar and choose **Edit**, or open **Management › Clients** and double-click the client. For a site, click **View Sites** on the client's row, then double-click the site. 2. Change **Name**, or the custom field values. 3. Click **Save**. Changing **Client** in a site's form moves the site, with all its devices, to the other client. **Delete a client or a site** 1. Right-click it in the sidebar, or in **Management › Clients**, and choose **Delete**. 2. If it has no devices, confirm with **Delete**. 3. If it has devices, pick the **Site to move agents to** and click **Move**, then confirm with **Delete**. The devices move to that site first, then the client or site is deleted. Deleting a client also deletes its sites and the deployment links of those sites. **Move devices to another site** * One device: open its **Edit** form, change **Site** and click **Save** — see [The device list](/sonar/administration/devices/device-list#edit-a-device). * Many devices: type `Bulk Organize Agents` in the header search box (**Search functionality...**) and open it. Pick the **Origin Site**, pick the destination in **Choose a destination site**, move devices across with **Add**, **Add all** or by dragging them, and click **Confirm Changes**. Nothing is saved until you confirm. ## What you should see The client appears in the **Clients** group of the sidebar on **Dashboard › Sysadmin**, with its sites underneath, and gets its own card in the **Clients overview**. Hover a client or site in the sidebar to see its ID and **Agent Count**. **Management › Clients** lists every client you can see with **Name**, **Total Agents** and **View Sites (N)**; **Add Client** creates one from there. **View Sites** opens **Sites for CLIENT-A**, with **New** to add a site. ## How to verify it worked * **Created, renamed or deleted**: **Reports & Audits › Audits** records an **Add Object**, **Modify Object** or **Delete Object** action with object **Client** or **Site**, your username, and the values before and after. * **Devices moved one by one**: the device's **Site** column shows the new site, and the audit trail has a **Modify** action on object **Agent**. * **Devices moved in bulk**: the audit trail has a **Bulk Action** entry that reads `jdoe moved N agent(s) to CLIENT-A - SITE-01`. Filter the device list by the destination site to see them. * **Deleted with devices**: select the destination site in the sidebar; the moved devices are listed there. ## Actions on a client or site Right-click a client or a site in the **Clients** group of the sidebar on **Dashboard › Sysadmin**: | Action | What it does | Permission | | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | Edit | Opens the client or site form | Manage Clients / Manage Sites | | Delete | Deletes it, moving its devices first when it has any | Manage Clients / Manage Sites | | Add Site | Creates a site under this client. Clients only | Manage Sites | | Enable Maintenance Mode / Disable Maintenance Mode | Puts every device of the client or site in maintenance mode, or takes them out. The console says how many devices changed. See [Maintenance mode](/sonar/administration/devices/device-details#maintenance-mode) | Run Bulk Operations, Edit Agent | | Install Agent | Opens the agent installer. Sites only | Install Agents | | Assign Automation Policy | Sets the **Server Policy** and **Workstation Policy** of the client or site, and **Block policy inheritance** | Manage Policies, plus Manage Clients / Manage Sites | | Assign Alert Template | Sets the alert template of the client or site | Manage Alert Templates, plus Manage Clients / Manage Sites | | Run URL Action | Opens a configured URL action for the client or site — see [URL actions](/sonar/administration/settings/url-actions) | Run URL Actions | | Run Checks | Runs the checks of every device in the client or site now | Run Checks | ## How clients and sites relate to the rest of SONAR * **Installers**: the agent installer asks for a **Client** and a **Site**, and the device registers in that site. A deployment link is tied to one site. Check both fields before you generate an installer — see [Deploy agents at scale](/sonar/deploy-operate/mass-deployment). * **Automation policies**: a client and a site each carry a server policy and a workstation policy. A device inherits the one that matches its **Type** from its site and from its client, alongside any policy assigned to the device itself, unless inheritance is blocked. The **Automation Policies** tab of the device's **Edit** form lists what applies — see [Automation policies](/sonar/administration/automation/automation-policies). * **Alert templates**: a client or a site can carry an alert template that its devices inherit — see [Alerts and alert templates](/sonar/administration/automation/alerts). * **Roles**: a role can be limited to some clients and sites in **Admin Center › Roles**. When a user whose role is limited this way creates a client or a site, SONAR adds it to that role, so the user keeps seeing what they created. See [Roles and permissions](/sonar/administration/identities/roles). * **Custom fields**: clients and sites have their own custom fields, filled in their forms — see [Custom fields](/sonar/administration/settings/custom-fields). ## Common errors | Symptom | Cause | Fix | | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------ | | `Client name cannot contain the \| character` or `Site name cannot contain the \| character` | The name has a `\|` | Remove it | | The client is not saved and the name field reports it already exists | Client names are unique | Pick another name | | `A client must have at least 1 site.` | You tried to delete the only site of a client | Create another site first, or delete the client | | `A client must have at least one site` | You changed the client of the only site of a client | Create another site in the original client first | | `There are no valid sites to move agents to. Add another site and try again` | The client or site has devices and there is nowhere else to move them | Create a site to receive them, then delete again | | **Confirm Changes** stays disabled with `Origin site and destination site cannot be the same.` | The destination is the origin site | Pick a different destination | | `No agents have been put in maintenance mode. You might not have permissions to the resources.` | None of the devices of that client or site is in your role's scope | Check the role's clients and sites | | A menu item is greyed out with `You don't have permission for this action` | Your role lacks the permission in the table above | Ask for the permission to be added to your role | ## Field reference **Client form** (**Create Client** / **Editing CLIENT-A**) | Field | What it does | Accepted values | Default | | ------------------ | ------------------------------------------------------------ | ------------------------------------- | ------------------- | | Name | Client name, shown in the sidebar, the list and the overview | Up to 255 characters, unique, no `\|` | — | | Default first site | Name of the site created with the client. Only when creating | Up to 255 characters, no `\|` | — | | Custom Fields | One input per client custom field | Depends on the field type | The field's default | **Site form** (**Create Site** / **Editing SITE-01**) | Field | What it does | Accepted values | Default | | ------------- | ---------------------------------------------------------------------- | ------------------------------------------------------- | --------------------------- | | Client | Client the site belongs to. Changing it moves the site and its devices | Any client you can see | The client you started from | | Name | Site name | Up to 255 characters, unique within the client, no `\|` | — | | Custom Fields | One input per site custom field | Depends on the field type | The field's default | Custom fields appear in the forms for roles with **View Custom Fields**. ## Related pages * [The device list](/sonar/administration/devices/device-list) * [Automation policies](/sonar/administration/automation/automation-policies) * [Roles and permissions](/sonar/administration/identities/roles) * [Deploy agents at scale](/sonar/deploy-operate/mass-deployment) * [Custom fields](/sonar/administration/settings/custom-fields) # Asset inventory Devices › Asset Inventory: the fleet-wide overview and the device, hardware, operating system, network and storage lists built from agent reports. ## What this is and when to use it **Devices › Asset Inventory** turns what the agents report about their hardware into fleet-wide views. Where the device panel answers a question about one machine, the inventory answers questions about all of them: how many laptops there are, which devices have less than 8 GB of RAM, which volumes are almost full, which machines miss critical Windows updates, which network adapters use DHCP. It has six screens, each an entry of the **Asset Inventory** group in the sidebar: **Overview**, **Devices**, **Hardware**, **Operating Systems**, **Network** and **Storage**. ## Before you start * A role with **List Agents** (**Admin Center › Roles**, group **Agents**). The **Asset Inventory** entries appear only for roles with it. * Devices with the agent installed and checking in. A device appears in the hardware, storage and network screens after its agent has sent its first inventory report. ## Steps 1. Open **Devices › Asset Inventory › Overview** for the fleet at a glance. 2. Click **TOTAL ASSETS**, **ONLINE** or **OFFLINE** to open the list of the devices behind that number, with a search box and page buttons. 3. Open one of the list screens — **Devices**, **Hardware**, **Operating Systems**, **Network** or **Storage** — for the detail. 4. Type a hostname in the search box and press Enter to narrow the list. 5. On **Devices**, use the operating system tabs and the **STATUS:** buttons to filter. 6. Use **ITEMS PER PAGE** and the page buttons to move through the list. ## What you should see Each screen opens with counters at the top and a list or charts below. The lists show 10 rows per page by default, with 25 and 50 available. ## How to verify it worked The inventory is built from data the agent already sent, so the check is whether that data is recent: 1. Open the device in **Dashboard › Sysadmin** and look at its **Assets** tab, or the **Home** cards. These show the agent's last report directly. 2. If a value is out of date, click the refresh icon in the panel header. The agent reports at once and the console shows `Agent WMI data refreshed successfully`. 3. Open the inventory screen again after the next refresh cycle, up to ten minutes later. The row shows the new value. ## Where the data comes from The agent reports its hardware inventory about once an hour and its disk usage more often. SONAR rebuilds the inventory tables from the latest report of each device every ten minutes, and the **Overview** figures with them. The online, offline and overdue counters are refreshed every five minutes. Hostname, operating system, IP addresses, logged-in user and status in the **Devices** list are read live from the device record. Manufacturer, model, processor, network adapters and physical disk details come from the Windows hardware inventory, so on Linux and macOS devices those columns can be empty and their adapters do not appear under **Network**. Any value a device does not report — a RAM type a virtual machine does not expose, for example — stays empty. ## The screens ### Overview Titled **ASSETS OVERVIEW**. | Element | What it shows | | ----------------------------- | --------------------------------------------------------------------------------------------------- | | TOTAL ASSETS, ONLINE, OFFLINE | Number of devices, and how many are online and offline. Click one to open the list of those devices | | WINDOWS, LINUX, MACOS | Devices per platform | | NOTEBOOKS, DESKTOPS, SERVERS | Devices per hardware type, as reported by the device | | Disks Near Full | Devices with at least one volume more than 90% used | | Missing Patches | Devices with at least one Critical Windows update not installed | | OS DISTRIBUTION | Devices per operating system | | MEMORY DISTRIBUTION | Devices per amount of RAM: < 8GB, 8GB, 16GB, 32GB+ | | VENDORS | Devices per hardware manufacturer | | DISK SIZE | Devices per total storage: < 256GB, 256GB, 512GB, 1TB+ | | CPU GENERATION | Devices per processor generation | ### Devices Every monitored device, with the counters **TOTAL ASSETS**, **ONLINE**, **OFFLINE**, **OVERDUE**, **WINDOWS**, **LINUX** and **MACOS**. * Tabs **All**, **Windows**, **Linux** and **macOS** filter by platform. * **STATUS:** **ALL**, **ONLINE**, **OFFLINE**, **OVERDUE** filters by each device's status, as in the device list. * Click a row to expand it and see its **CPU**, **RAM** and **DISK**. | Column | What it shows | | ---------------- | ------------------------------------------------------------------------------------------------- | | HOSTNAME | Device name | | TYPE | Hardware type reported by the device | | OPERATING SYSTEM | Name and version | | IP ADDRESS | Local addresses reported by the agent | | STATUS | `online`, `offline` or `overdue` — see [Status](/sonar/administration/devices/device-list#status) | | DEPARTMENT | Site the device belongs to | | USER | User logged in on the device | | LAST CONTACT | Time since the last check-in | The counters at the top use the same fixed windows as the clients overview in **Dashboard › Sysadmin**, while the **STATUS:** filter uses each device's own **Offline after** and **Overdue after**. The two can differ for devices in maintenance mode, archived devices, and devices with custom times. ### Hardware One row per device, with the counter **TOTAL DEVICES**. | Column | What it shows | | --------------- | ------------------------------------------------- | | HOSTNAME | Device name | | VENDOR / MODEL | Manufacturer and model | | CPU | Processor model | | CORES / THREADS | Physical cores and logical processors | | RAM | Installed memory | | DISK | Size of the primary disk, normally the `C:` drive | | DISK USAGE | How full the primary disk is | ### Operating Systems One row per device, with the counters **TOTAL**, **UPDATED**, **PENDING** and **CRITICAL**, and an **OS DISTRIBUTION** chart. | Column | What it shows | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | HOSTNAME | Device name | | OS | Operating system name | | VERSION / BUILD | Version and build number | | ARCHITECTURE | Processor architecture of the operating system, such as `X64` | | DOMAIN | Domain or workgroup the device belongs to | | UPTIME | Time since the last boot | | LAST PATCH | When the patch schedule last started installing updates on the device | | PATCH STATUS | Critical when a Critical Windows update is not installed; pending when an Important, Moderate or Low update is not installed; updated otherwise | The **UPDATED**, **PENDING** and **CRITICAL** counters apply the same rule to the whole fleet. For the updates themselves, see [Windows Updates across the fleet](/sonar/administration/patching/windows-updates). ### Network One row per physical network adapter, with the counter **TOTAL INTERFACES**. Virtual adapters and adapters without a MAC address are left out. | Column | What it shows | | ----------- | ------------------------------------------------ | | HOSTNAME | Device the adapter belongs to | | ADAPTER | Adapter name | | MAC ADDRESS | Hardware address | | IP ADDRESS | IPv4 address assigned to the adapter | | GATEWAY | Default gateway | | DNS | DNS servers | | SPEED | Link speed | | DHCP | Whether the address comes from DHCP or is static | ### Storage One row per volume, with the counters **TOTAL DISKS** and **CAPACITY** (the sum of all volumes). | Column | What it shows | | ---------- | ----------------------------------------- | | HOSTNAME | Device the volume belongs to | | DRIVE | Drive letter or mount point | | MODEL | Model of the physical disk | | CAPACITY | Size of the volume | | USAGE | How full the volume is | | PARTITIONS | Number of partitions on the physical disk | ## Common errors | Symptom | Cause | Fix | | --------------------------------------------------------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | `Could not load inventory overview` with **TRY AGAIN** | The overview figures are being prepared; they are rebuilt every ten minutes | Wait a few minutes and click **TRY AGAIN** | | A new device is missing from **Hardware**, **Storage** or **Network** | Its first inventory report has not been processed yet | Wait for the next ten-minute cycle | | A value is out of date | The inventory shows the device's last report | Use the refresh icon in the device panel, then wait for the next cycle | | A search finds nothing | The search box matches the hostname only | Search by hostname | | A column is empty for a device | The device does not report that value | Check the device's **Assets** tab for what it reports | ## Related pages * [Device details](/sonar/administration/devices/device-details) — the **Assets** tab of one device * [The device list](/sonar/administration/devices/device-list) * [Software inventory](/sonar/administration/software/software-inventory) * [Windows Updates across the fleet](/sonar/administration/patching/windows-updates) # Remote access | Page | What it covers | | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Remote control](/sonar/administration/remote-access/remote-control) | Take control of a device's desktop from the console: the remote window, what the person at the endpoint sees, multiple displays, clipboard, and the audit record. | | [Remote terminal](/sonar/administration/remote-access/remote-terminal) | Open a command shell on a Windows, Linux, or macOS device from the remote window, choose the shell and the account it runs as, and find the audit record. | | [Transfer files](/sonar/administration/remote-access/file-transfer) | Browse a device's file system from the remote window, upload and download files, and edit, zip, rename, or delete them. | | [Processes, services, and event logs](/sonar/administration/remote-access/processes-services-events) | List and end processes, start, stop, and reconfigure Windows services, and read Windows event logs from the Processes, Services, and Logs tabs of the remote window. | # Remote control Take control of a device's desktop from the console: the remote window, what the person at the endpoint sees, multiple displays, clipboard, and the audit record. ## What this is and when to use it **Take Control** opens a remote window for one device. On a Windows device the window starts on the **Take Control** tab, which shows the device's desktop and lets you use its mouse and keyboard from the browser. The same window holds the other remote tools: **Terminal**, **File Browser**, **Processes**, **Services**, and **Logs**. Use it when you need to see what the user sees, work through an installer, or fix something that needs the graphical session. The desktop, terminal, and file sessions run through the **remote access service**, which reaches the device through a second agent installed next to the SONAR agent. The console shows that agent's state separately, as the remote status. The SONAR agent can be online while the remote access agent is offline, and the other way round. On the endpoint, the remote access agent appears as: | Platform | Service | | -------- | ----------------------------------------------------------------------- | | Windows | The **Mesh Agent** service, installed under `%ProgramFiles%\Mesh Agent` | | Linux | `meshagent.service` | | macOS | The `meshagent` launch daemon | {% hint style="info" %} The desktop tab exists only for Windows devices. On Linux and macOS devices the remote window opens on **Terminal**, and the **Services** and **Logs** tabs are not shown. {% endhint %} ## Before you start * A role with **List Agents** (section **Agents**) and **Use Mesh** (section **System**) in **Admin Center › Roles**. The API checks **Use Mesh** before it opens a session. If your role is limited to some clients or sites, you can open sessions only on devices in those clients and sites. * The device's remote status is **Remote Online**. It is shown in the header of the device panel. ## Steps 1. Open **Dashboard › Sysadmin**, open a client card or **All clients**, and select the device. The device panel opens under the list. 2. Check the status pills in the panel header. **Remote Online** means you can continue. 3. Click **Take Control** in the panel header. You can also choose **Take Control** in the **Other actions** menu (the ⋮ button in the panel header), or right-click the device row in the list and choose **Take Control**. 4. In the new window, wait for **Loading remote session** to clear. 5. Click **Connect** to start the desktop. 6. Work on the device. Clear **Input** if you want to watch without sending mouse or keyboard input. 7. Click **Disconnect** when you finish, then close the window. ## What you should see The window title reads `WS-0001 - CLIENT-A - SITE-01 | Remote Background`: the device, its client, and its site. Across the top are the tabs, then two status badges: the SONAR agent status and the remote status, for example **Online** and **Remote online**. After **Connect**, the status beside the button stops reading **Disconnected** and the device's desktop fills the window. ### Controls in the desktop view | Control | What it does | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Connect** / **Disconnect** | Starts and ends the desktop session | | **Connect**, right-click | **Ask Consent** asks the person at the device before the session starts, **Privacy Bar** shows them the connection bar, and **Ask Consent + Bar** does both, whatever the consent settings of your deployment | | **Disconnect**, right-click | **Disconnect and Lock** ends the session and locks the device's screen | | **Input** | Turns mouse and keyboard input on or off. Off means view only | | Key list and **Send** | Sends a key combination your own computer would keep for itself. The list includes Ctrl + Alt + Del, Win + L, Win + R, Alt + Tab, and Alt + F4 | | **Clipboard** | Opens the **Remote Clipboard** dialog. **Get Clipboard** copies the endpoint's clipboard text into the box. **Set Clipboard** puts the text in the box on the endpoint's clipboard. Text only, up to 65,535 characters | | Display icons | Appear when the endpoint has more than one display. Each icon switches the view to one display, and **All Displays** shows them all at once | | Session time | Shows how long the desktop session has been open | When the window opens, your browser may ask whether the page can read the clipboard. Allow it if you want copy and paste to work between your computer and the endpoint. ### What the person at the endpoint sees The consent settings of the remote access service decide what the person signed in to the device sees. These settings are part of your deployment and are set up with DataDike implementation support. The options are: | Option | What the person at the endpoint sees | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Consent prompt | A window with the message "*name* requesting remote desktop access. Grant access?" and the buttons **Allow** and **Deny**. *Name* is the SONAR user who is connecting. The session starts only after **Allow**. While the prompt is open, your remote window shows "Waiting for user to grant access..." | | Auto accept, Windows only | The prompt has a third choice, **Auto accept all connections for next 60 minutes**. Once it is chosen, new desktop, terminal, and file sessions from the same SONAR user start without a prompt for 60 minutes. The period ends early if the remote access agent restarts | | Notification | A system notification: "*name* started a remote desktop session." | | Connection bar | A bar on the desktop that reads "Sharing desktop with: *name*" for as long as the session lasts. If the person closes the bar, the remote desktop session ends | If no consent option is set, the session starts without a prompt and without a notification. ### When the remote status is not online If the remote access agent is offline, the panel shows **Remote Offline** and **Take Control** is disabled. Its tooltip starts with "You cannot take control of this agent". If the SONAR agent is online at the same time, the panel also shows **Restart Remote Service**, which asks the SONAR agent to restart the remote access agent on the device. If the remote window is opened while the remote status is anything other than online, it shows **Remote access unavailable**, the two status badges, and a **Close** button. No session starts and no audit record is written. ## How to verify it worked 1. Open the session and click **Connect**. The status beside the button must stop reading **Disconnected**, and the desktop must follow your mouse. 2. In the device panel, open the **Audits** tab. A new entry with the action **Remote Session** must be at the top, with your username, the device, and your IP address under **Client IP**. 3. For the whole environment, open **Reports & Audits › Audits** and filter by the **Remote Session** action. {% hint style="info" %} SONAR writes one **Remote Session** record each time the remote window opens for a device, and another each time **Restart Mesh Agent** completes in that window. The record says who opened the window, for which device, when, and from which IP address. One record covers the **Take Control**, **Terminal**, and **File Browser** tabs of that window together. It does not record what was done during the session or when the session ended. {% endhint %} ## Common errors | Symptom | Cause | Fix | | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Take Control** is disabled, with **Remote Offline** in the panel | The remote access agent on the device is not connected | If the SONAR agent is online, click **Restart Remote Service**. If it is not, bring the device online first, then check that the **Mesh Agent** service (Windows), `meshagent.service` (Linux), or the `meshagent` launch daemon (macOS) is running | | **Take Control** in the menu is greyed out, with "You don't have permission for this action" | Your role does not have **Use Mesh** | Ask an administrator to add it in **Admin Center › Roles** | | The remote window opens but no session loads in any tab | Your role does not have **Use Mesh** | Ask an administrator to add it in **Admin Center › Roles** | | The window shows **Remote access unavailable** | The remote status was not online when the window opened | Close the window, refresh the device panel, and try again when it shows **Remote Online** | | Nothing opens after you click **Take Control** | The browser blocked the new window | Allow pop-ups for the console address | | The remote window shows "Waiting for user to grant access..." and no desktop appears | The person at the endpoint has not clicked **Allow**, or clicked **Deny** | Contact the user and try again | | There is no **Take Control** tab in the remote window | The device runs Linux or macOS | Use **Terminal** and **File Browser** | | "Unable to contact the agent" after **Restart Remote Service** or **Restart Mesh Agent** | The SONAR agent did not answer | Wait until the device shows **Online** and try again | ## Field reference **Device panel header**: | Element | What it shows or does | | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | **Online** / **Overdue** / **Offline** | SONAR agent status | | **Remote Online** / **Remote Offline** / **Remote Unknown** | Remote access agent status, read when the panel loads. **Remote Unknown** means the console could not get an answer | | **Take Control** | Opens the remote window. Disabled while the remote status is **Remote Offline** | | **Restart Remote Service** | Shown only when the remote status is **Remote Offline** and the SONAR agent is online. Restarts the remote access agent on the device | | **Other actions** (⋮) | Opens the device action menu. **Take Control** is its first entry | **Remote window, top right**: | Element | What it does | Available on | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | Status badges | SONAR agent status and remote status | All platforms | | **Restart Connection** | Restarts the **Mesh Agent** Windows service through the SONAR agent. Needs **Manage Windows Services** in your role. Confirms with "Mesh agent service was restarted" | Windows | | **Restart Mesh Agent** | Asks the SONAR agent to stop and start the remote access agent, then reloads the remote tabs. Confirms with "Repaired mesh agent on *device*". Can be used again after 10 seconds | All platforms | | SONAR logo | Switches the window between light and dark mode | All platforms | **Remote window tabs**: | Tab | What it opens | Available on | | ---------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------- | | **Take Control** | Remote desktop | Windows | | **Terminal** | Command shell on the device. See [Remote terminal](/sonar/administration/remote-access/remote-terminal) | All platforms | | **File Browser** | The device's file system. See [Transfer files](/sonar/administration/remote-access/file-transfer) | All platforms | | **Processes** | Running processes. See [Processes, services, and event logs](/sonar/administration/remote-access/processes-services-events) | All platforms | | **Services** | Windows services | Windows | | **Logs** | Windows event logs | Windows | The **Mesh Central** tab in **Admin Center › Settings** connects the console to the remote access service. It is maintained with DataDike implementation support. ## Related pages * [Remote terminal](/sonar/administration/remote-access/remote-terminal) — the command shell in the same window * [Transfer files](/sonar/administration/remote-access/file-transfer) — the file browser in the same window * [Device details](/sonar/administration/devices/device-details) — the device panel and its status pills * [Audit trail](/sonar/administration/audit/audit-trail) — where **Remote Session** records appear * [Roles and permissions](/sonar/administration/identities/roles) — **Use Mesh** and the other remote access permissions # Remote terminal Open a command shell on a Windows, Linux, or macOS device from the remote window, choose the shell and the account it runs as, and find the audit record. ## What this is and when to use it The **Terminal** tab of the remote window opens an interactive command shell on the device, in your browser. Use it for work that is faster at a prompt than on the desktop: checking a configuration file, restarting a daemon, reading a log, running a one-off command while you watch the output. It works on Windows, Linux, and macOS devices. On Linux and macOS it is the tab the remote window opens on, because the desktop tab exists only for Windows. The terminal runs through the remote access service, like the remote desktop, so it needs the remote access agent on the device to be online. To run a command without an interactive session, or on many devices at once, use [Run a command or a script on a device](/sonar/administration/automation/run-commands-and-scripts) instead. ## Before you start * A role with **List Agents** and **Use Mesh** in **Admin Center › Roles**. There is no separate permission for the terminal: **Use Mesh** covers the desktop, the terminal, and the file browser. * The device shows **Remote Online** in the device panel. * For **User Shell** or **User PowerShell**, a user signed in to the device. ## Steps 1. Open **Dashboard › Sysadmin**, select the device, and click **Take Control**. See [Remote control](/sonar/administration/remote-access/remote-control) for the other ways to open the remote window. 2. Click the **Terminal** tab. 3. To open the default shell, click **Connect**. To choose the shell, right-click **Connect** and pick one from the list. The shells are listed in the field reference below. 4. Wait for the prompt, then type your commands. 5. Click **Disconnect** when you finish. ## What you should see The status next to **Connect** stops reading **Disconnected**, and the shell's prompt appears in the terminal area. The bar under the terminal shows **Session time**, a list of special keys with **Send**, and buttons for **Ctl-C**, **Ctl-X**, and **ESC**, for keys your browser would otherwise keep. If the consent settings of your deployment require it, the person signed in to the device is asked first, with the message "*name* requesting remote terminal access. Grant access?". Your terminal shows "Waiting for user to grant access..." until they answer. The **Ask** entries in the Windows shell list always ask, whatever the settings. What the person at the endpoint sees is described in [Remote control](/sonar/administration/remote-access/remote-control). ## How to verify it worked 1. Run a command whose answer you know, such as `hostname` or `whoami`. The output must show the device's name, and the account the shell runs as. 2. Open the **Audits** tab of the device panel. The **Remote Session** entry written when you opened the remote window must be there, with your username. {% hint style="info" %} The terminal is covered by the single **Remote Session** record that SONAR writes when the remote window opens. The commands you type are not recorded in SONAR. If you need a record of a command and its output, run it with **Send Command** from the device action menu instead, which keeps the command and its output in the device's **History** tab. {% endhint %} ## Common errors | Symptom | Cause | Fix | | ----------------------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | The **Terminal** tab shows **Remote access unavailable** | The remote access agent was not online when the window opened | Wait for **Remote Online** in the device panel and open the window again. See [Remote control](/sonar/administration/remote-access/remote-control) | | "Waiting for user to grant access..." and no prompt appears | The person at the endpoint has not clicked **Allow**, or clicked **Deny** | Contact the user, or connect with a shell that does not ask | | "PowerShell is not supported on this version of windows" | The device's Windows version has no PowerShell the terminal can start | Use **Admin Shell** or **User Shell** | | **User Shell** or **User PowerShell** does not open | No user is signed in to the device | Use **Admin Shell** or **Admin PowerShell** | | **Login Shell** asks for a user name | It starts the device's own login | Sign in with an account that exists on the device | ## Field reference Shells in the **Connect** right-click list: | Shell | Runs as | Platform | | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | ------------ | | **Admin Shell** | Command Prompt with administrative rights. This is what **Connect** opens on Windows | Windows | | **Admin PowerShell** | PowerShell with administrative rights | Windows | | **User Shell** | Command Prompt as the user signed in to the device | Windows | | **User PowerShell** | PowerShell as the user signed in to the device | Windows | | **Ask Admin Shell**, **Ask Admin PowerShell**, **Ask User Shell**, **Ask User PowerShell** | The same four shells, with a consent prompt shown to the person at the device first | Windows | | **Root Shell** | `bash` as root, or `sh` where `bash` is missing. This is what **Connect** opens on Linux and macOS | Linux, macOS | | **User Shell** | The shell as the user signed in at the device's console | Linux, macOS | | **Login Shell** | The device's login prompt. You sign in with a user name and password of the device | Linux, macOS | Controls in the terminal: | Control | What it does | | ----------------------------- | ---------------------------------------------------------------------- | | **Connect** / **Disconnect** | Opens and closes the shell. Right-click **Connect** for the shell list | | **Session time** | How long the shell has been open | | Special key list and **Send** | Sends the selected key to the shell | | **Ctl-C**, **Ctl-X**, **ESC** | Send those keys to the shell | ## Related pages * [Remote control](/sonar/administration/remote-access/remote-control) — the remote window, remote status, and consent * [Transfer files](/sonar/administration/remote-access/file-transfer) — move files to and from the same device * [Run a command or a script on a device](/sonar/administration/automation/run-commands-and-scripts) — commands that are kept in the device's history * [Audit trail](/sonar/administration/audit/audit-trail) — the **Remote Session** record # Transfer files Browse a device's file system from the remote window, upload and download files, and edit, zip, rename, or delete them. Works on Windows, Linux, and macOS. ## What this is and when to use it The **File Browser** tab of the remote window opens the file system of the device in your browser. From it you can move files between your computer and the device, and manage files on the device without opening a desktop session. Use it to collect a log file, drop an installer or a configuration file on a machine, or clean up a folder. It works on Windows, Linux, and macOS devices, and runs through the remote access service, like the remote desktop and the terminal. ## Before you start * A role with **List Agents** and **Use Mesh** in **Admin Center › Roles**. **Use Mesh** covers the desktop, the terminal, and the file browser; there is no separate permission for files. * The device shows **Remote Online** in the device panel. ## Steps ### Open the file browser 1. Open **Dashboard › Sysadmin**, select the device, and click **Take Control**. See [Remote control](/sonar/administration/remote-access/remote-control) for the other ways to open the remote window. 2. Click the **File Browser** tab. 3. Click **Connect**. To ask the person at the device for consent first, right-click **Connect** and choose **Ask Consent**. 4. Click a folder to open it. **Up** goes back to the parent folder, and the current path is shown above the list. On Windows the top level lists the drives: open a drive before you upload, create, or delete anything. ### Download files from the device 1. Tick the files you want. 2. Click **Download**. Each selected file is saved by your browser. **Download** takes files only. To download a folder, tick it, click **Zip** to make an archive of it on the device, then tick the archive and download it. ### Upload files to the device 1. Open the destination folder. 2. Click **Upload**, choose one or more files, and confirm. You can also drag files from your computer onto the file list. 3. If a file with the same name is already in the folder, confirm the message "Upload will overwrite 1 file. Continue?" or cancel. 4. Wait for the progress bar to finish. ### Delete files on the device 1. Tick the files or folders. 2. Click **Delete** and confirm "Delete selected item?". When the selection includes a folder, tick **Recursive delete** to remove the folder with everything in it. ## What you should see After **Connect**, the status stops reading **Disconnected** and the list shows the folders and files of the current location, with their size and date. The two lists on the right change how sizes are shown (**Human Readable**, **Bytes**, **Kilobytes**, **Megabytes**, **Gigabyte**) and how the list is sorted (by name, size, or date). If the consent settings of your deployment require it, or if you chose **Ask Consent**, the person signed in to the device sees "*name* requesting remote file Access. Grant access?" and must click **Allow**. Until then the file browser shows "Waiting for user to grant access...". If the settings ask for a notification, they see "*name* started a remote file session." instead. ## How to verify it worked 1. After an upload, click **Refresh**. The file must be in the folder with the size of the original. 2. After a download, open the file on your computer and compare its size with the size shown in the file browser. 3. After a delete, click **Refresh**. The items must be gone. 4. In the device panel, open the **Audits** tab. The **Remote Session** entry written when you opened the remote window must be there, with your username. {% hint style="info" %} The file browser is covered by the single **Remote Session** record that SONAR writes when the remote window opens. The individual uploads, downloads, and deletions are not recorded in SONAR. {% endhint %} ## Common errors | Symptom | Cause | Fix | | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | | The tab shows **Remote access unavailable** | The remote access agent was not online when the window opened | Wait for **Remote Online** in the device panel and open the window again | | The buttons stay greyed out | The file browser is not connected yet, nothing is ticked, or you are at the drive list of a Windows device | Click **Connect**, tick an item, or open a drive | | **Download** stays greyed out | A folder is among the ticked items | Untick the folder, or zip it first | | "Only files less than 200k can be edited." | **Edit** opens only files up to 200 KB | Download the file, edit it on your computer, and upload it again | | "Waiting for user to grant access..." and the list stays empty | The person at the device has not clicked **Allow**, or clicked **Deny** | Contact the user and try again | | A folder is not removed | **Recursive delete** was not ticked | Delete again and tick **Recursive delete** | ## Field reference | Button | What it does | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------- | | **Connect** / **Disconnect** | Opens and closes the file session. Right-click **Connect** for **Ask Consent** | | **Up** | Goes to the parent folder | | **Select All** | Ticks every item in the current folder | | **Rename** | Renames the ticked item | | **Delete** | Deletes the ticked items, after confirmation. **Recursive delete** appears when a folder is ticked | | **Edit** | Opens one ticked file in a text editor in the browser. Files up to 200 KB | | **New Folder** | Creates a folder in the current location | | **Upload** | Sends one or more files from your computer to the current folder. Asks before overwriting a file with the same name | | **Download** | Saves the ticked files to your computer. Files only, not folders | | **Cut**, **Copy**, **Paste** | Move or copy the ticked files to another folder on the device | | **Zip** | Makes a `.zip` archive of the ticked items on the device | | **Unzip** | Extracts the ticked `.zip` file into a folder you choose, in the **Unzip To Folder** dialog | | **Refresh** | Reloads the current folder | | **Find** | Searches for files by name under the current folder | | **GoTo** | Opens a folder by typing its path | | **Open** | Opens the ticked file or folder on the device's own desktop, after confirmation | ## Related pages * [Remote control](/sonar/administration/remote-access/remote-control) — the remote window, remote status, and consent * [Remote terminal](/sonar/administration/remote-access/remote-terminal) — a command shell on the same device * [Processes, services, and event logs](/sonar/administration/remote-access/processes-services-events) — the other tabs of the remote window * [Audit trail](/sonar/administration/audit/audit-trail) — the **Remote Session** record # Processes, services, and event logs List and end processes, start, stop, and reconfigure Windows services, and read Windows event logs from the Processes, Services, and Logs tabs of the remote window. ## What this is and when to use it Three tabs of the remote window work without a desktop session: | Tab | What you can do | Platforms | | ------------- | ---------------------------------------------------------------------------------- | --------------------- | | **Processes** | See the running processes with their CPU, memory, and user, and end one | Windows, Linux, macOS | | **Services** | See the Windows services, start, stop, or restart one, and change its startup type | Windows | | **Logs** | Read the Windows **Application**, **System**, and **Security** event logs | Windows | Use them to find what is using a machine's memory, restart a service that stopped answering, or read the errors around a failure, without interrupting the person working at the device. These tabs are answered by the SONAR agent, not by the remote access agent, so nothing appears on the device's screen while you use them. The remote window itself opens only when the device shows **Remote Online**. ## Before you start * A role in **Admin Center › Roles** with **List Agents** and **Use Mesh**, to open the remote window, and the permission for each tab: | Tab | Permission | Section in **Roles** | | ------------- | --------------------------- | ---------------------- | | **Processes** | **Manage Processes** | **System** | | **Services** | **Manage Windows Services** | **Software & Updates** | | **Logs** | **View Event Logs** | **Logs** | The API checks each permission, and a role limited to some clients or sites works only on devices in those clients and sites. * The device's SONAR agent is online, because every request goes to it. ## Steps Open the remote window first: open **Dashboard › Sysadmin**, select the device, and click **Take Control**. See [Remote control](/sonar/administration/remote-access/remote-control) for the other ways in. ### Processes 1. Click the **Processes** tab. The list loads and refreshes every 2 seconds. 2. Type in **Search** to filter the list, or click a column header to sort it. 3. To slow down or speed up the refresh, change **Interval** with **−** and **+**. The shortest interval is 1 second. 4. To freeze the list while you read it, click **Stop Live Refresh**. Click **Resume Live Refresh** to start again. 5. To end a process, right-click its row and choose **End Process**. {% hint style="warning" %} **End Process** runs as soon as you click it, with no confirmation step, and it also ends the processes started by that one. Check the **PID** before you click. {% endhint %} ### Services (Windows) 1. Click the **Services** tab. The list shows every Windows service on the device. 2. Right-click a service and choose **Start**, **Stop**, or **Restart**. The action runs at once and the list reloads. 3. To change how the service starts, double-click it, or right-click it and choose **Service Details**. 4. In the dialog, choose the **Startup type** and click **Save**. **Save** is available only when the value differs from the current one. {% hint style="warning" %} Stopping or disabling the **Mesh Agent** service ends remote access to the device, and stopping or disabling the `sonarrmm` service disconnects the SONAR agent. Neither can be undone from the console while it is down. {% endhint %} ### Event logs (Windows) 1. Click the **Logs** tab. It opens the **Application** log for the last day. 2. Choose **Application**, **System**, or **Security**. 3. Choose how far back to read in **Show last *****N***** days**. The list reloads each time you change the log or the period. 4. Type in **Search** to filter the rows. 5. Click the text in the **Message** column to read the full message. Reading the **Security** log, or a long period, takes longer. The console waits up to 30 seconds for the **Application** and **System** logs and up to 3 minutes for **Security**. ## What you should see **Processes** shows a live table and, above it, two totals: CPU, green below 50 %, yellow from 50 %, red from 80 %, and RAM in use against the device's total memory. After **End Process**, the console shows "Process with PID: *number* was ended successfully" and the process leaves the list at the next refresh. **Services** shows each service with its startup type and status. After an action, the console shows "The service was started successfully", "The service was stopped successfully", "The service was restarted successfully", or, after **Save**, "The service start type was updated successfully". **Logs** shows the events newest first, with their type, source, event ID, and time. ## How to verify it worked 1. **End Process**: the process must disappear from the list at the next refresh. If it comes back with a new **PID**, something on the device started it again. 2. Service action: the **Status** column must show the new state after the list reloads. Click the refresh button above the list to read it again. 3. Startup type: open **Service Details** again. **Startup type** must show the value you saved, and the **Startup** column shows it in the list. 4. Event log: compare the newest event with the time of the problem you are investigating. If the list is empty, widen **Show last *****N***** days**. The **Remote Session** entry written when you opened the remote window is the audit record of the visit, in the device's **Audits** tab and in **Reports & Audits › Audits**. The actions on these three tabs do not add entries of their own; use the checks above to confirm them. ## Common errors | Symptom | Cause | Fix | | -------------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | "Unable to contact the agent" | The SONAR agent did not answer in time | Check that the device is **Online** in the device panel and try again. For the **Security** log, choose a shorter period | | A tab loads but stays empty, or an action is refused | Your role does not have the permission for that tab | Ask an administrator for **Manage Processes**, **Manage Windows Services**, or **View Event Logs** | | There are no **Services** or **Logs** tabs | The device runs Linux or macOS | Only **Processes** is available on those platforms | | **Start**, **Stop**, or **Save** shows an error message from Windows | Windows refused the change, for example a disabled service or a dependency | Read the message, fix the cause on the device, and try again | | A **Stop** takes up to half a minute | The console waits for the service to report that it stopped | Wait for the message | | **End Process** reports an error | The process could not be ended, for example because it already exited | Refresh the list and check the **PID** | | Some event messages are empty | The event's source has no message text registered on that device | Use the **Source** and **Event ID** to look the event up | ## Field reference **Processes** columns and controls: | Field | What it shows or does | | ----------------------------------------------- | -------------------------------------------------- | | **Name** | Process name | | **CPU** | Processor use reported for the process, in percent | | **Memory** | Memory the process holds in RAM | | **User** | Account the process runs as | | **PID** | Process ID | | **Stop Live Refresh** / **Resume Live Refresh** | Stops and restarts the automatic refresh | | **Interval** | Seconds between refreshes. Default 2, minimum 1 | | **Search** | Filters the rows | **Services** columns: | Field | What it shows | | ---------------- | --------------------------------------------------------------- | | **Display Name** | Name shown in Windows | | **Name** | Service name | | **Startup** | Startup type. **Automatic (Delayed)** when the start is delayed | | **PID** | Process ID of a running service | | **Status** | Current state, such as running or stopped | | **Log On As** | Account the service runs as. **LocalSystem** when none is set | **Service Details** dialog: | Field | What it does | Accepted values | | ------------------------------------------------------------- | ----------------------------------- | ---------------------------------------------------------------------- | | **Service name**, **Display name**, **Description**, **Path** | Read only | — | | **Startup type** | How Windows starts the service | **Automatic (Delayed Start)**, **Automatic**, **Manual**, **Disabled** | | **Service status** | Current state, read only | — | | **Start**, **Stop**, **Restart** | Run the action and close the dialog | — | | **Save** | Applies the new **Startup type** | Enabled only after a change | **Logs** fields: | Field | What it does | Accepted values | Default | | ---------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------- | --------------- | | Log | Which Windows log to read | **Application**, **System**, **Security** | **Application** | | **Show last *****N***** days** | How far back to read | 1, 2, 3, 4, 5, 10, 30, 60, 90, 180, 360, 9999 | 1 | | **Search** | Filters the rows | Free text | Empty | | **Type** | Event level | INFO, WARNING, ERROR, SUCCESS, AUDIT\_SUCCESS, AUDIT\_FAILURE | — | | **Source**, **Event ID**, **Time** | Event origin, number, and time | — | — | | **Message (click to view full)** | The first characters of the message. Click for the full text | — | — | ## Related pages * [Remote control](/sonar/administration/remote-access/remote-control) — the remote window and the remote status * [Checks](/sonar/administration/automation/checks) — watch a service or an event log continuously instead of by hand * [Run a command or a script on a device](/sonar/administration/automation/run-commands-and-scripts) — act on processes and services with a script that is kept in history * [Roles and permissions](/sonar/administration/identities/roles) — **Manage Processes**, **Manage Windows Services**, **View Event Logs** # Automation | Page | What it covers | | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [Script library](/sonar/administration/automation/scripts) | Build and maintain the script library under Management › Scripts: create, upload, clone, test, favorite, hide and download scripts, and reuse code with snippets. | | [Run a command or a script on a device](/sonar/administration/automation/run-commands-and-scripts) | Send a shell command or run a library script on one device, choose what happens to the output, and find every run in the device's History tab. | | [Run actions across many devices](/sonar/administration/automation/bulk-actions) | Send one command, one script or one patch action to every device of a client, a site, a hand-picked list or your whole scope, filtered by operating system and device type. | | [Automated tasks](/sonar/administration/automation/automated-tasks) | Schedule scripts and commands on a device or through a policy: triggers, actions, collector tasks, run now, how Windows and Linux/macOS schedule them, and where the results appear. | | [Checks](/sonar/administration/automation/checks) | Monitor devices with checks (CPU load, disk space, memory, ping, Windows service, event log, script): thresholds, failure counts, intervals, run now, reset, run history and alerts. | | [Automation policies](/sonar/administration/automation/automation-policies) | Group checks, tasks, a patch policy and an alert template into an automation policy, assign it to clients, sites or devices, and control inheritance, precedence and exclusions. | | [Alerts and alert templates](/sonar/administration/automation/alerts) | Work with alerts raised by overdue devices, failing checks and failing tasks, and configure alert templates: channels, severities, resends, actions, exclusions and where templates apply. | --- [Next Page](https://wiki.datadike.com/llms-full.txt/1)