Using Windows Command Line Programs
This chapter provides a summary of the command line programs you can run on computers that have the Agent for Windows installed to perform troubleshooting and administrative operations.
Using CopyGroup and CopyGroupNested
The CopyGroup and CopyGroupNested commands help you provision users when there are trust relationships between domains. You can use them to mirror group membership and group hierarchy from a trusted domain and forest to a target domain and forest.
These utilities are located in the Zone Provisioning Agent’s Tools folder.
To use these command line utilities, you must have an account that can log on to the trusted source domain and the target domain. The account should also have read permission on the source domain and permission to update the target domain.
For example, assume you have configured the AJAX domain to have a one-way trust with the DEVOPS domain and you have your Active Directory users and groups defined in the DEVOPS domain. If you want to allow the users and groups in the DEVOPS domain to log on to computers that are joined to the AJAX domain, you can log on to the AJAX domain controller with an account that has administrative privileges in both the AJAX and DEVOPS domains, then run the CopyGroup utility to mirror the group membership from a group in the DEVOPS source domain as zone users in the AJAX target domain.
For more information about the command line arguments and options for these utilities, see the usage message displayed for each utility.
Using dzinfo
The dzinfo command line program provides detailed information about the effective rights, role definitions, and role assignments for a specified user. The command output includes all of the same information that you can view using the Authorization Center as described in Using the Authorization Center directly on managed computers. However, using dzinfo as a command line utility allows you to view and capture all of the output from the command in a single window, which you can then save as a text file for troubleshooting and analysis or in reports.
The syntax for the dzinfo program is:
dzinfo [/v] [user_name] [/h]
The /v is an optional argument that enables you to view verbose output for the command. The user_name is an optional argument that enables you to view information for the specified user account. However, you must be logged on as a local administrator to specify the user_name argument. If you log on with an account that does not have local administrative privileges you cannot return authorization information for another user account.
If you run the dzinfo command without the user_name argument, the command returns authorization information for the currently logged-on user account.
The command returns detailed information about the rights, roles, and role assignments for the specified user (richl in the AJAX domain) similar to the following:
From the Access Manager
Effective roles for AJAX\richl:
Domain Admin/portland
Zone: CN=portland,CN=global,CN=Zones,OU=Acme,DC=ajax,DC=org
Status: Active
Windows Login/global
Zone: CN=global,CN=Zones,OU=Acme,DC=ajax,DC=org
Status: Active
Effective Login Rights for AJAX\richl:
Console Login: Permitted
Audit Level: Audit if possible
Remote Login: Permitted
Audit Level: Audit if possible
PowerShell Remote Access: Permitted
Audit Level: Audit if possible
Role Assignments for AJAX\richl:
Domain Admin/portland
Status: Active
Account: AJAX\richl
Scope: Zone
Zone: ajax.org/Acme/Zones/global/portland
Local Role: No
Network Role: Yes
Effective: Immediate
Expires: Never
Windows Login/global
Status: Active
Account: AJAX\Domain Admins
Scope: Zone
Zone: ajax.org/Acme/Zones/global
Local Role: Yes
Network Role: No
Effective: Immediate
Expires: Never
Role Definitions:
Domain Admin/portland
Status: Active
Description: None
Zone: CN=portland,CN=global,CN=Zones,OU=Acme,DC=ajax,DC=org
Login Permitted: No
Audit Level: Audit if possible
Rescue Right: No
Require MFA: No
Available Hours: All
Rights:
ADUC/portland
Type: Application
Description: None
Priority: 0
Run As: AJAX\Administrator
Application: mmc.exe
Path: C:\Windows\system64
C:\Windows
C:\Program Files
C:\Program Files (x86)
C:\Windows\SysWOW64
Arguments: "C:\Windows\system64\dsa.msc"
Match Case: No
Require Authentication: No
Application Criteria:
None
Domain Admin Network Access/portland
Type: Network Access
Description: None
Priority: 0
Run As: AJAX\Administrator
Require Authentication: No
Windows Login/global
Status: Active
Description: Predefined system role for general Windows login users.
Zone: CN=global,CN=Zones,OU=Acme,DC=ajax,DC=org
Login Permitted: Console & Remote & PowerShell Remote
Audit Level: Audit if possible
Rescue Right: No
Available Hours: All
Rights:
None
Computer is joined to zone ajax.org/Acme/Zones/global/portland
Auditing for AJAX\richl:
Session ID 2:
Desktops:
Default: Not currently auditing.
Auditing is not available on this computer.
Using dzjoin
The dzjoin command line program enables you to automatically join users to the zone in which their roles and rights are assigned, or to join them to a specific zone by zone name, when they log on to their computer. The dzjoin command line program is particularly useful for organizations that use non-persistent virtual desktop infrastructures.
The syntax for the dzjoin command is:
dzjoin [/c <domain controller>] [/d] [/u <username>] [/f] [/h] [/r [yZZ_BAR_ZZnZZ_BAR_ZZyesZZ_BAR_ZZno]] {/z <zonename> ZZ_BAR_ZZ /s ZZ_BAR_ZZ /v]
{b}Note: {/b}If the u option is specified but no password is found in the redirected input, you will be prompted for a password.
| Use this option | To do this |
|---|---|
| /c | Specify a domain controller to connect to. |
| /d | Retrieve zone data before restarting |
| /u | Specify the user name to join zone using custom credentials. The user name must be in the format: USER@DOMAIN or DOMAIN\USER. The credentials are for remote access only. For the password, you can specify by redirected input. Otherwise, this tool will prompt user for password. |
| /f | Suppress any warnings and/or questions. |
| /h | Displays the command help. |
| /r | Suppress the restart warning and specify to restart machine, if required, after joining zone. If no restart is required, this option is ignored. If no argument is provided, e.g. '/r', the default is to restart (example: '/r yes'). |
| /z | Join a zone using the zone name. If the zone name is not unique, use the canonical name instead. |
| /s | Join to the zone where this computer is already pre-created in the zone or had previously been joined to the zone (but remotely left in a disconnected situation). |
| /v | Display the agent version. |
You can also use the PowerShell command Join-CdmZone to join a zone.
Using dzleave
To leave a zone, use the dzleave command. The syntax for the dzleave command is:
dzleave [/c <domain controller>] [/u <username>] [/a|/f] [/r [yZZ_BAR_ZZnZZ_BAR_ZZyesZZ_BAR_ZZno]] [/v] [/h]
| Use this option | To do this |
|---|---|
| /a | Remove the role assignment from the computer zone. |
| /c | Specify a domain controller to connect to. |
| /u | Specify the user name to leave zone using custom credentials. The user name must be in the format: USER@DOMAIN or DOMAIN\USER. The credentials are for remote access only. For the password, you can specify by redirected input. Otherwise, this tool will prompt user for password. |
| /f | Suppress any warning and/or question(s). In case the domain cannot be contacted, this tool will perform a local zone leave automatically. |
| /h | Displays the command help. |
| /r | Specify whether to restart machine, if required, after leaving zone without prompt. If no restart is needed, this option is ignored. If no argument is provided, example: '/r', the default is to restart ('/r yes'). |
| /v | Show the agent version. |
You can also use the PowerShell command Exit-CdmZone to leave a zone.
Using dzdiag
The dzdiag command line program provides detailed diagnostic information for the local computer. The command output includes all of the same information that you can view by clicking Diagnostics on the Troubleshooting tab as described in Running diagnostics and viewing logs for the agent.
The syntax for the dzdiag command is:
dzdiag [/h] [/o]
The /h is an optional argument that displays the command help.
The /o is an optional argument that allows you to output just the offline MFA provisioning information. You can use this option to see if a user has configured an offline MFA profile or not and details about their offline MFA configuration.
You must be logged on as a local administrator to run the dzdiag command.
The command returns detailed information about desktop sessions similar to the following:
Product: Verify Privilege Server Suite version-number ( build-number)
Computer: SERVER01
Joined Domain: acme.local
Zone: acme.local/Program Data/Centrify/Zones/global
Auditing: Available
Agent State: Connected
Time: 2018-10-04 17:41:41.491 -07:00
Session information:
Session 3
SAM Name: SERVER01\Administrator
Logon Type: Console
Always Audit: Yes
Desktops:
Default
GUID: 3e2c9799-b398-459f-a7a2-ed3a5359af3f
DZ Logon Id: (0x0)
Local Role: Self
Network Roles: Self
Audit Status: Currently Auditing
UAC Restrictions: No
Network Drives: No
Logon information:
Logon ID (0x5bd925)
Logon GUID: 50972030-e9ed-45dc-b7b7-ecf588ef152d
Base Logon ID: (0x1aff6e)
Base SAM Name: ACME\admin
ElevatedAccount: (ElevatedSelfAccount, AdditionalGroups=(count=1,
items=(S-1-5-32-544)))
Local Role: Windows Login/CN=global,CN=Zones,CN=Acme,CN=Program
Data,DC=acme,DC=local
Network Roles: None
Should Audit: Yes
Logon ID (0x5c2fe6)
Logon GUID: 053ef6cd-10cc-4383-b614-437c1a2067e3
Base Logon ID: (0x1aff6e)
Base SAM Name: ACME\admin
ElevatedAccount: (ElevatedSelfAccount, AdditionalGroups=(count=1,
items=(S-1-5-32-544)))
Local Role: Windows Login/CN=global,CN=Zones,CN=Acme,CN=Program
Data,DC=acme,DC=local
Network Roles: None
Should Audit: Yes
Logon ID (0x5deca8)
Logon GUID: ce0da851-90f5-4cb6-a71b-25e2b116be75
Base Logon ID: (0x1aff6e)
Base SAM Name: ACME\admin
ElevatedAccount: (ElevatedServiceAccount,
ServiceAccount=S-1-5-21-1132289714-2257106472-2904894658-500)
Local Role: Windows Login/CN=global,CN=Zones,CN=Acme,CN=Program
Data,DC=acme,DC=local
Network Roles: None
Should Audit: Yes
Logon ID (0x613c40)
Logon GUID: 8ca4e342-4f4a-4e85-8e05-4d1332272c31
Base Logon ID: (0x1aff6e)
Base SAM Name: ACME\admin
ElevatedAccount: (ElevatedServiceAccount,
ServiceAccount=S-1-5-21-1132289714-2257106472-2904894658-1108)
Local Role: Windows Login/CN=global,CN=Zones,CN=Acme,CN=Program
Data,DC=acme,DC=local
Network Roles: None
Should Audit: Yes
Domain last access information:
Forest acme.local: Connected and Agent can authenticate
Domains:
acme.local (ACME): Connected
The offline MFA provisioning information:
None
Multi-factor Authentication information:
Platform Instance: https://tenant.my.centrify.net/
Last Used Platform Instance: <none>
Platform Certificate Exists: No
Disable Web Proxy: No
AD Site: Default-First-Site-Name
Platform Instance Override: <none>
Connector Override: <none>
MFA Enabled (NotJoined): No
Platform Instance (NotJoined): <none>
Web Proxy: <none>
Connectors:
Connector: server01.acme.local
FQDN: server01.acme.local
Tenant: https://tenant.my.centrify.net/
Last Known Availability: Yes
Last Access Time: -
IWA Enabled: Yes
IWA HTTPS Port: 8443
Proxy Enabled: Yes
Proxy Server: server01.acme.local:8080
AD Site: Default-First-Site-Name
Using dzrefresh
The dzrefresh command line program enables you to refresh the authorization cache from a Command Prompt window. Running the dzrefresh command provides the same functionality as clicking Refresh on the Troubleshooting tab in the local agent configuration panel as described in Performing cache operations.
The syntax for the dzrefresh command is:
dzrefresh
You must be logged on as a local administrator to run the dzrefresh command. The command output indicates whether the refresh of the authorization cache is successfully initiated.
Using dzflush
The dzflush command line program flushes the authorization cache and reloads all authorization information from Active Directory. Depending on the size of the authorization store, users might experience a temporary loss of the ability to use the rights granted to them while the authorization information is reloaded. To prevent any loss of access privileges, in most cases you should use the dzrefresh command instead of the dzflush command to ensure that the agent is using the latest authorization information. You should only use the dzflush command if IBM Security Support recommends that you do so.
The syntax for the dzflush command is:
dzflush [/h] [/l]
| Use this option | To do this |
|---|---|
| /h | Show the command usage. |
| /l | Synchronize local Windows account information between Access Manager and the Windows systems where local account management is enabled. Note: Local account management is not supported on domain controllers. |
You must be logged on as a local administrator to run the dzflush command. The command output indicates whether the authorization cache is successfully flushed.
Using dzdump
The dzdump command line program enables you to view and capture the current content of the authorization cache. You can use command line options to control the information contained in the output for the command.
The syntax for the dzdump command is:
dzdump [/d [directory-path] ] [/w=screen-width] [/s] [/n] [/g] [/l] [/a]
[/r] [/i] [/t] [/z] [/u] [/h]
If you specify no command line arguments, the dzdump command returns complete in memory information from the authorization agent (dzagent) cache. You can use the following command line arguments to refine the output for the command:
| Use this option | To do this |
|---|---|
| /d | Dump cache files from the default location or a specified location. You can use this option with a directory path to dump cache files from a specified location. For example, to dump cache files from the directory C:\AcmeAZstore:/d=C:\AcmeAZstore Note that you cannot use the /d option to dump cache files directly on a computer where the Agent for Windows is currently running. However, you create a copy of the cache, then dump the cache from the saved copy. For example, copy all files in the cache directory—the default location for cache directory is c:\ProgramData\Centrify\DirectAuthorize\Cache—to a temporary directory. You can then dump the authorization cache by running dzdump and specifying the temporary location. |
| /w | Use the specified screen-width for word-wrapping the command output. If you don’t specify this options, the default screen width is 80 characters. To disable word-wrapping of the command output, specify a screen-width of zero. For example: /w=0 |
| /s | Display security identifier (SID) mappings |
| /n | Display name mappings |
| /g | Display assignee mappings |
| /l | Display assignments in the joined zone hierarchy |
| /a | Display assignments for security identifiers (SID) |
| /r | Display role definitions |
| /i | Display right definitions |
| /t | Display access token information |
| /z | Display zone hierarchy |
| /u | Display recent user logon activity |
| /h | Displays the command help |
You can use any combination of display options to display only the information of interest. If you do not specify any display options, the dzdump command displays all of the information in the authorization cache.
You must be logged on as a local administrator to run the dzdump command. You should note that the command output from a dzdump command can contain sensitive information. You should only use the dzdump command if IBM Security Support recommends that you do so.
Depending on the display options you specify, the command returns detailed information about the authorization cache.
Using runasrole
The runasrole command-line program enables you to run a specified Windows application using a specified access role. You can use command line options to control whether the role is used as a local role, a network role, or both, and whether to use the current environment or the environment variables associated with the “Run As” user account. The runasrole command line program is equivalent to selecting the Run with Privilege menu option when right-clicking an application shortcut or executable.
The syntax for the runasrole command is:
runasrole /role:role[/zone] [options] application [argument]
runasrole /localrole:role[/zone] [options] application [argument]
runasrole /networkrole:role[/zone] [options] application [argument]
You must specify the role to use in the rolename/zonename format. You must also specify an appropriate path to the application you want to access, including any required or optional arguments.
You can use the following command line arguments and options with the runasrole command:
| Use this option | To do this |
|---|---|
| /role | Use the role name you specify as both a local role and a network role. You can specify this option to run an application locally and access a remote server using the same role, if applicable. You should only use this option if the role you are assigned and want to use has both local and network access rights defined. |
| /localrole | Use the role name you specify as a local role. |
| /networkrole | Use the role name you specify as a network role. |
| /env | Use the current environment variables instead of the environment variables associated with the "Run As" user account. |
| /netdrives | Use mapped network drives when running an application with the selected role. By default, you cannot use mapped network drives that are associated with you logged-on user account when running applications using a role with elevated privileges. If you want to use a mapped network drive when accessing an application using a selected role, include the /netdrives option in the command line. |
| /removetimestamp | Remove the grace period on Windows authentication and MFA for the current user session. |
| /wait | Prevents the runasrole program from exiting immediately after opening the specified application. If you specify this option, the runasrole program starts the specified application and waits until the application session ends before exiting. When the application session ends, the runasrole program exits and returns the same result code as the application. If you specify this option and the application is a command line utility, the runasrole program redirects the application's input and output to the command line console. You should note that some applications use a Microsoft API that does not support redirection of standard input and output. For applications that don’t support redirection, the /wait option has no effect and is ignored. |
| /h | Displays the command help. |
Examples
To use the same role to open the Computer Management application locally and access a remote server in zone1, you might run a command similar to the following:
runasrole /role:role1/zone1 mmc.exe c:\windows\system64\compmgmt.msc
To use the role named SQLdba from the finance zone as a local role to open the Services application, you might run a command similar to the following:
runasrole /localrole:SQLdba/finance mmc.exe c:\windows\system64\services.msc
To use role1 from zone1 as a local role to open the Computer Management application and use network access rights from role2 in zone2, you might run a command similar to the following:
runasrole /localrole:role1/zone1 /networkrole:role2/zone2 mmc.exe compmgmt.msc
To open the Services application using the role named SQLdba from the finance zone and have the runasrole program remain open until you close the Services application, you might run a command similar to the following:
runasrole /wait /role:SQLdba/finance mmc.exe c:\windows\system64\services.msc
Running an application from a shortcut
In most cases, you can use the runasrole program to run specified Windows applications using the application shortcut. However, there are many different types of application shortcuts and the RunAsRole program does not support all of them. You can use the RunAsRole program to execute applications with the following recognized shortcut target extensions:
.bat
.cmd
.cpl
.exe
.msc
.msi
.msp
.ps1
.vbs
.wsf
How to determine whether RunAsRole supports an application shortcut
You can determine whether you can use the RunAsRole program to execute an application from the application shortcut by checking the file extension for the target application in the application’s shortcut properties dialog box.
To check the file extension for a target application shortcut
-
Select an application shortcut.
-
Right-click the shortcut, then click Properties to display the file properties.
-
Click the Shortcut tab and check the target field.
If the target file extension displayed is a supported file extension, you can use RunAsRole to execute the application from the application shortcut.You should note that a shortcut target field might include both the filename for the application executable and one or more arguments. As long as the application executable has a supported file extension, you can useRunAsRole to execute the application with the specified arguments from the shortcut. For example, if the shortcut target isC:\Windows\System64\control.exe printers, the application executableC:\Windows\System64\control.exe is a supported file extension with printers supplied as an argument. Therefore, you would be able use RunAsRole to run the application from its shortcut.
Using RunAsAlternate
The runas alternate command line program enables you to log in to an application using an alternate account.
For example, system administrators typically have several accounts, a user account for general log-ins and an administrative account to access specific systems and services.
The syntax for the runas alternate command is:
runas alternate [/account:accountname] application [argument] [/h]
You can use the following command line arguments to refine the output for the command:
| Use this option | To do this |
|---|---|
| application | Run an application using the alternate account set in Privileged Access Service. |
| argument | (optional) Specify an application argument |
| /account accountname | Specify the alternate account owned by this user for which the application is to be run. This can be useful in cases where a user has more than one alternate account. |
| /h | Display the command help |
If you have only one alternate account defined, you don't need to specify the /account option.
For more information about alternate accounts, see Enabling users to run applications with alternate accounts.