The Goverlan Command Line Utility

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?

This utility is called GovCmdLine.exe and is located in the installation directory of Goverlan (i.e.: C:\Program Files\Goverlan Reach Console 9). 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.

Using GovCmdLine Help System

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.

Using the /HELP:Alias parameter

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.

Using the /HELP:Show(x) and /HELP:ShowArg(x) parameters

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  http://assets.goverlan.com/userguide_img/images/cmd%20util%20-%20figure%20A.png

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.

GovCmdLine Execution Flags

For an execution, the GovCmdLine requires at least two pieces of information: a target and an action.

Defining the target

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.

Defining Report Actions

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 above). An attribute can also be substituted by its alias if it has been configured.

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

Defining Set Actions

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 above). An attribute can also be substituted by its alias if it has been configured (see Working with Aliases below).

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)

Defining Execute Actions

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 above). A method name can also be substituted by its alias if it has been configured (see Working with Aliases below).

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 simply GovCmdLine -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).

Defining Actions using a Definition File

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.

Working with Aliases

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.

Example

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 below:

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.
TEXT > The report is displayed as text in a friendly format. Each line is formatted as NAME: VALUE

For instance:

Name: John
LastName: Doe
Location: New York

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
Doe
New York

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’

 

Was this article helpful?

Related Articles