Windows Agent Manual Install & Post Installation Steps
A Cimitra Agent is deployed to any of the Windows computers you want to run commands or scripts on. Cimitra Agents are deployed after you have implemented a Cimitra Server.
Cimitra Agent Setup Overview
- Define the Cimitra Agent in Cimitra Administration
- Download the Cimitra Agent EXE and CONFIG Files
- Install the Cimitra Agent in a PowerShell console
NOTE: The Cimitra Agent will install as a Windows service.
Defining a Cimitra Agent for Windows
- Log into the Cimitra Web Client as an admin-level user
- Choose Agents
- Add Agent
- Name the agent and choose the Windows Platform
Download The Cimitra Agent for Windows
NOTE: You will probably need to define an exception in the anti-virus software on the Windows computer to be able to download and run the cimagent.exe file.
- Click on the newly created Cimitra Agent for Windows
- Download the Agent File (cimagent.exe)
- Download the Config File (cimitra.cfg)
- Put both files on the Windows computer you are installing to
Cimitra Agent Installation
- Open a PowerShell session, make sure to Run as Administrator when establishing your PowerShell session.
- Issue the command to install the Cimitra Agent as follows:
.\cimagent.exe install -config “<path to config file>”
Example:
.\cimagent.exe install -config “c:\cimitra\cimitra.cfg”
Once the installation process completes, in PowerShell use the Start-Service Cimitra command to start the Cimitra Agent as a Windows Service.
Start-Service Cimitra
To see if the Cimitra Agent is running as a Windows Service issue the Get-Service Cimitra command.
The Cimitra Agent on Windows generally needs additional configuration. For example, you generally want to run the Cimitra Windows Agent Service as a specific user. There may also be PowerShell script execution rights that you may need to set. Read the “Enable PS Script” sections for instructions on how to enable PowerShell script execution rights.
Enabling PowerShell Scripts
Enabling PowerShell script execution can sometimes be a challenge. The steps to do so are extremely fluid and every changing with each Windows release.
Recently we discovered these simple steps for enabling PowerShell scripts in a certain directory to run un-impeded.
- In a PowerShell session, go to the directory where you have the PowerShell scripts stored on a Windows computer where you have the Cimitra Agent deployed.
- Issue the following commands:
cd c:\cimitra\scripts
Unblock-File *
Set-ExecutionPolicy Unrestricted
Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope Process
Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser
Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope LocalMachine
Set-ExecutionPolicy Bypass
Viewing Execution Policies
Get-ExecutionPolicy
Get-ExecutionPolicy -List
Running the Cimitra Agent Service as an Admin-Level User
If the steps you took earlier do not allow the Cimitra Agent to successfully run PowerShell scripts, then you should configure the Cimitra Agent Service to run as an Admin-level user on the Windows computer. Do the following:
- Run the Windows Service App
- Run services.msc from the Windows start button
- Find the Cimitra Agent Service
- Edit the Properties of the Cimitra Agent
- Choose: Log On
- Select: This account
- Fill in the credentials for an Admin-level user
- Restart the Cimitra Agent Service
Troubleshooting and Alternative Steps
If you are still unable to get Windows to allow you to run PowerShell scripts here is some help to try and get PowerShell to allow script execution. In June of 2020, a customer site upgraded to the latest version of Windows 10. They tried all of the “Set-Execution” type steps first. None of the steps worked. Then they came upon a solution in which they had to define the Cimitra PowerShell Apps in the following manner: [ CLICK HERE ]
Use “ExecutionPolicy ByPass -File”
NOTE: This is a last resort step if all the previous methods of enabling PowerShell script execution did not work.
When creating a Cimitra App that runs a PowerShell script or command define the Cimitra App Fields as you normally would. However, the Script/Command field should be pre-appended with the “-ExecutionPolicy Bypass -File” directive, as shown below:
Script/Command:
-ExecutionPolicy ByPass -File <path to PowerShell script>
Example:
-ExecutionPolicy ByPass -File C:\Cimitra\scripts\date_test.ps1
Restarting the Cimitra Agent Service
Whenever you change values in PowerShell or Regedit in order to affect PowerShell Scripting execution, it’s important to restart the Cimitra Agent Service. You can do that with the PowerShell command:
Restart-Service Cimitra
After running the Restart-Service Cimitra command, see if you can run the PowerShell script via a Cimitra App.
Advanced Cimitra Agent Installation
Additional Cimitra Agent Instances
Perhaps you want to run a second instance of the Cimitra Agent on the same Windows computer. This can be useful in circumstances in which you want to assure that a Cimitra Agent is associated with a user that is limited in their rights within an Active Directory Tree.
One customer had this scenario, to read more [CLICK HERE]
If you want to install a second instance of the Cimitra Agent then do the following:
- Create another Cimitra Agent for Windows, just as you did before, give it a different name.
- Install the Cimitra Agent using the “instance” command as follows:
.\cimagent.exe install -config “<path to config file>” -instance:<instance name>
Example:
.\cimagent.exe install -config “c:\cimitra\cimitra.cfg” -instance:CIMWIN1
In PowerShell use the Start-Service “Cimitra$CIMWIN1“ command to start the Cimitra Agent as a Windows Service.
Start-Service “Cimitra$CIMWIN1“
Use the Get-Service “Cimitra$CIMWIN1“ command to see if the Cimitra Agent is running.
The Cimitra Agent can be run in the foreground for troubleshooting purposes. To run the Cimitra Agent in the foreground follow these steps
- Stop the Cimitra Agent Windows Service: Stop-Service Cimitra
- From the directory where the Cimitra Agent EXE file is, run cimagent.exe using the “–run and -runconfig” switches in the following manner:
.\cimagent –run -runconfig “c:\cimitra\cimitra.cfg”
Example Output:
Now try and run a Cimitra App associated with the Cimitra Agent to observe the behavior of the Cimitra Agent.
Uninstalling the Cimitra Windows Agent using Windows Service PowerShell commands as follows:
Remove-Service ‘Cimitra‘
If you installed additional instances of the Cimitra Agent use the “-instance” switches in the following manner:
Remove-Service ‘Cimitra$CIMWIN1‘