The Goverlan Command Line utility is used to perform remote administration tasks at the command line. The GovCmdLine utility has an extensive set of parameters which allow you to configure virtually every action that a Goverlan Scope Action is capable of doing. In other words, you can perform any task that Goverlan has to offer at the command prompt and in scripts.
Where can I find the utility
Using GovCmdLine Help System
Using /HELP:Show(x)_and_/HELP:ShowArg(x)
GovCmdLine Execution Flagsu
Working with Aliases (GovCmdLine.ini)
Options
This utility is called GovCmdLine.exe and is located in the installation directory of Goverlan (i.e.: C:\Program Files\Goverlan v6). To use it, open a command prompt and navigate to the Goverlan installation directory.
The GovCmdLine utility can be moved to another directory. However, if you do so, the following applies:
The utility has a set of external dependencies which are: GovBase.dll, GovBaseUI.dll, GovCmn.dll, GovTalkClt.dll, GovUIExt.dll and GovCmdLine.ini.
If you want the utility to have the capability to update or install the Goverlan Agents on a target machine, the following agent files must be included as well:
GovAppLog.dll, GovCPL.CPL, GoverRMS.exe, GovRMHook.dll, GovSrv.exe and psapi.dll.
Even if the GovCmdLine is a command line utility, it still requires a valid license registration like Goverlan.
Before explaining the available command line parameters, it is better to understand the available help options so that you don't have to refer to this help guide to use GovCmdLine. GovCmdLine includes a full help system which describes the parameters, provides examples, and can even list the available attributes, methods and method arguments of each object.
Note: Whenever you type a command line which results in large text output, you can always append a '| MORE' option at the end to have output in page mode. The output text is not displayed all at once but only one screen-size page at a time. In page mode, press the [ENTER] key to view the next line or the [SPACE] key to view the next page. Example: GovCmdLine /HELP | MORE displays the help documentation in page mode.
To view a synopsis of all parameters, simply type GovCmdLine without any parameters. After the initial definition of the parameters, a help command section is included:
HELP COMMANDS:
GovCmdLine /HELP => Displays extended parameter and help definitions.
GovCmdLine /HELP:Alias => Displays the available attribute aliases.
GovCmdLine /HELP:Show(objectLocator) => Displays the available attributes for an object.
GovCmdLine /HELP:ShowArg(methodLocator) => Displays the required arguments for a method.
GovCmdLine /HELP:Examples => Displays examples.
Let's define some of these help commands.
The command line parameters are used to specify the object attributes to report, set, or to specify the methods to execute. The actual attribute and method names are directly derived from the Scope Action features. For example, the user object has a scope action root attribute named 'User Principal Name'. If you were to request GovCmdLine to report this attribute for the user MYDOM\MYUSER, you would type the command line:
GovCmdLine -U:MYDOM\MYUSER -R:User Principal Name
Note: The -U and -R flags are explained later.
Some scope action attribute names are quite long and typing their full length name at the command prompt is tedious. For this reason, you can create attribute and method aliases. An alias is a short name for an attribute name (aliases are explained later in this article). You can view the full list of configured aliases by using the /HELP:Alias flag.
As mentioned earlier, object properties specified in the command line are directly derived from the Goverlan Scope Action feature. Since hundreds of properties and methods are available, it would be quite hard to remember them all. The /HELP:Show(x) and /HELP:ShowArg(x) flags can be used to browse the available properties and methods at the command line.
Use the Show(x) flag to display the available properties, child objects and methods of an object.
Use the ShowArg(x) flag to display the required parameters for an object method.
The only argument of the Show and ShowArg flag (that is 'x') is the full path of a parent object or method. There are three root objects in Goverlan: User, Computer, Group. These objects are always your starting point.
Typing: GovCmdLine /HELP:Show(User) displays the available properties and methods for the user object.
Typing: GovCmdLine /HELP:Show(Computer) displays the available properties and methods for the computer object.
Typing: GovCmdLine /HELP:Show(Group) displays the available properties and methods for the group object.
The Show flag displays information in four categories: Attribute Sets, Attributes (read only), Attributes (read/write), Methods. Each entry that is displayed can be used in a command line parameter.
To view the available properties of a child object, type the full path of the child object including its parent. For instance, the User root object has a child object called 'Logged-in Computers'. To view the properties of this type, you would type GovCmdLine /HELP:Show(user.logged-in computers). An object path may include as many child objects as needed.
Figure A
The ShowArg flag is used to view the expected arguments of the specified method. Since a method call requires all arguments to be specified in its defined order, you will find this help flag useful. For example, the computer root object has a method called 'Set RMC Client Settings'. To view the expected arguments for this method, you would type: GovCmdLine /HELP:ShowArg(Computer.Set RMC Client Settings). The result is displayed in Figure A.
Now that you have a better idea of how to use the help system, let's look at the actual execution flags.
For an execution, the GovCmdLine requires at least two pieces of information: a target and an action.
Use the {-U:|-M:|-G:}AccountName flags to specify a target, where -U: is to target a user, -M: is to target a machine, -G: is to target a group. Then specify the name of the target after the comma.
Examples:
GovCmdLine -U:ORION\JDoe ... targets the user account for John Doe on domain ORION.
GovCmdLine -U:\\SOMEMAC\Administrator ... targets the local user account Administrator on machine SOMEMAC.
GovCmdLine -M:ORION\SOMEMAC ... targets the computer SOMEMAC on domain ORION.
GovCmdLine -M:213.125.41.13 ... targets the computer with IP address 231.125.41.13
GovCmdLine -G:ORION\Schema Admins ... targets the group Schema Admins in the domain ORION.
GovCmdLine -G:\\SOMEMAC\Administrators ... targets the local group Administrators on machine SOMEMAC.
Use the -R:A1,A2,...,Ai flag to define reporting actions. To specify multiple attributes, separate them with a comma. The available attributes depend on the object type of the target (see Using the /HELP:Show). An attribute can also be substituted by its alias if it has been configured (see Working with Aliases).
For example, the Computer root object has an attribute set named 'Memory Information' (see Figure A). To report on the memory information of target SOMEMAC, you would type:
GovCmdLine -M:SOMEMAC -R:Memory Information
The Computer object also has a child object: Shares, which has the attribute set: Share Information. To report the memory information and the shares information of target SOMEMAC, you would type:
GovCmdLine -M:SOMEMAC -R:Memory Information,Shares.Share Information
Use the -S:Atr1(val1),Atr2(val2),...,Atri(vali) flag to define set actions. To modify multiple attributes, separate them with a comma. The available write attributes depend on the object type of the target (see Using the /HELP:Show). An attribute can also be substituted by its alias if it has been configured (see Working with Aliases).
For example, the User root object has a writable attribute set named 'Password'. To change the password of the domain user account ORION\JDoe, you would type:
GovCmdLine -U:ORION\JDoe -S:Password(userNewPassword)
To change the password of the domain user account ORION\JDoe, and set this new password as expired, you would type:
GovCmdLine -U:ORION\JDoe -S:Password(userNewPassword),Password Expired(TRUE)
Note: When entering the value of a boolean value, you can either use the strings {TRUE|FALSE} or {0|1}
To change the password of the local user account JDoe on machine JDMACNAME you would type:
GovCmdLine -U:\\JDMACNAME\JDoe -S:Password(userNewPassword)
Use the -E:M1(a1,a2,...),M2(a1,a2,...),...,Mi(a1,a2,...) flag to define execute actions. To execute multiple actions, separate them with a comma. The available methods depend on the object type of the target (see Using the /HELP:Show and /HELP:ShowArg). A method name can also be substituted by its alias if it has been configured (see Working with Aliases).
A method may have 0 or more arguments. For instance, the computer object includes the 'Install / Update Agents' method. This method doesn't require any arguments. Therefore, you would call it by typing:
GovCmdLine -M:SOMEMAC -E:Install / Update Agents() or simplyGovCmdLine -M:SOMEMAC -E:Install / Update Agents
The computer object also has a method named 'Add New Local User' which requires 8 arguments. To create a local user account you would type:
GovCmdLine -M:SOMEMAC -E:Add New Local User(jdoe,John Doe,some user,jdpassword,TRUE,FALSE,TRUE,FALSE)
Note: To view the arguments definition of this method, you would type: /HELP:ShowArg(Computer.Add New Local User).
The -R, -S and -E flags provide a lot of flexibility and are straight forward to use. However, configuring a command line parameter for sophisticated actions would be tedious. When you need to execute complicated actions (such as selecting WMI objects), it is best to define them in a Scope Action or Custom Action first, then use the definition flag in a parameter.
Use the -F:aDefFile flag to have the utility use a external action definition file, where 'aDefFile' is the file name or full path of either a Scope Action definition file (.gsa) or a Custom Action definition file (.gca). If you do not specify a path, the Application Data directory as defined in the Options is used.
Use the Goverlan Management Console to create either a custom action object or a scope action object with the desired actions (for a scope action, insert a dummy target object). Then execute the configured actions using the GovCmdLine utility by using the -F: flag.
Note: Another advantage of using a scope action or custom action definition file is that you can configure conditions as well.
For example, if you have a scope action named 'Hardware Inventory' which is configured to report all hardware information of a machine, you would type:
GovCmdLine -M:SOMEMAC -F:Hardware Inventory.gsa
If you have a custom action named 'Apply Reg Hotfix2332' which is configured to import a registry file onto a machine, you would type:
GovCmdLine -M:SOMEMAC -F:Apply Reg Hotfix2332.gca
Note: You can copy a custom action definition file or scope action definition file from its default directory to any directory you wish. In which case, the -F: value should have the full path and name of the definition file. To open the default scope action definition directory, right click within the scope action view and select Open Scope Actions Directory. To open the default custom action definition directory, select any custom action, right click on the mouse and select Open Custom Actions Directory from the menu.
The attribute and method names specified using the -R, -S and -E flags can be lengthy and tedious to write. The GovCmdLine utility allows you to configure aliases for attributes and method names which can then be used in as parameters. This is done by editing the GovCmdLine.ini file which is located under the same directory as the GovCmdLine.exe program. If the GovCmdLine.ini file doesn't exist, you can create a new one as long as you respect the format.
The GovCmdLine.ini file has two categories: OPTIONS and ALIASES. We will explain the OPTIONS category later. Here is an example of the ALIASES category:
###########################################
# ALIASES CATEGORY
#
ALIASES:
Lock = Lock Workstation
ActInfo = All User Account Information
mActInfo = All Computer Account Information
AgentsInstall = Goverlan Agents.Install / Update Agents
usrMachine = Logged-in Computers.NT Account Name,Logged-in Computers.Computer Account Information.Location
The aliases category must start with the line 'ALIASES:'. Every subsequent line is treated as an alias entry, except for comment lines which start with a '#'. An alias entry is defined with the format: ALIAS = ACTION_NAMES, where ALIAS is the short name which maps to one or more attributes as defined in ACTION_NAMES.
The ACTION_NAMES part must respect the following rules:
You can enter any type of property: Attribute, Attribute Set, Child Object and Methods are all valid as long as the string is identical to the one you type at the command line.
Entering multiple values for a single attribute is done with commas separating each value. Note: All attributes must be of the same type. You cannot mix Report attributes with Set or Execute attributes.
When specifying a set or execute attribute, you can also enter the arguments. For instance, you can configure the actions: Set user password to 'welcome' and expire the password with the alias: usrResetPwd = Password(welcome),Password Expired(1) You would then type the command line: GovCmdLine -U:DOM\USR -S:usrResetPwd . If you do not specify the arguments in the alias definition, then you must enter them at the command line.
GovCmdLine -U:ORION\JDOE -R:Logged-in Computers.NT Account Name,Logged-in Computers.Computer Account Information.Location
Reports a user's logged-in machine information (name and location).
If you create the alias: usrMachine = Logged-in Computers.NT Account Name,Logged-in Computers.Computer Account Information.Location, the command line then becomes:
GovCmdLine -U:ORION\JDOE -R:usrMachine
Use the -O:o1=v1,o2=v2,...,oi=vi flag to set miscellaneous options as described bellow:
|
OPTION |
VALUES |
DESCRIPTION |
|
AUTOINSTALL |
{0|1} |
TRUE : Automatically installs the Goverlan Agents if they are required to complete the configured actions and if the remote machine is not equipped with them. FALSE : Do not automatically install the Goverlan Agents. If they are required to complete the configured actions and the remote machine is not equipped with them, the call fails. Default value: As configured in the Goverlan Management Console or as configured in the GovCmdLine.ini file. |
|
AUTOUPDATE |
{0|1} |
TRUE : Automatically updates the Goverlan Agents if they are required to complete the configured actions and if the remote machine is equipped with a different version. FALSE : Do not automatically update the Goverlan Agents. If they are required to complete the configured actions and the remote machine is equipped with a different version, the call fails. Default value: As configured in the Goverlan Management Console or as configured in the GovCmdLine.ini file. |
|
OUTPUT |
{XML|TEXT|TEXT_UNDECORATED} |
Specifies the desired output format if one or more report actions have been configured. XML > The report is displayed as XML fragments. For instance: Name: John TEXT_UNDECORATED > The report is displayed as text in a raw format. Only the values are displayed. This format may be easier to use in scripts. For instance: John Default value: TEXT |
To specify the options, use the -O:optionName=value format. For instance, the command line:
GovCmdLine -U:ORION\JDOE -R:usrInfo -O:AUTOINSTALL=1,OUTPUT=XML requests the Goverlan Agents to be automatically installed if needed and to report the information in XML.
You can modify the default values for each option in the GovCmdLine.ini file in the OPTION CATEGORY. Enter each option on a single line in the format: 'OPTION_NAME = OPTION_VALUE'